[30388f42] Docs: Add development and production workflow guidelines to RELOCATION.md

This commit introduces comprehensive guidelines for managing development and production environments, addressing the user's strategic questions regarding workflow, webhook handling, and secure email sending. - **Teil 4: Entwicklungs- vs. Produktions-Workflow:** Documents the 'separated worlds' approach for development on Synology and production on the Wackler VM, detailing configuration separation, webhook handling, and safe email testing. - **Teil 5: Alternative - Single-Host-Setup:** Provides a robust strategy for running both development and production environments on a single VM, emphasizing directory structure, port conflict resolution, and guaranteed database isolation via Docker volumes. These additions clarify the operational guidelines for maintaining system stability and data integrity post-migration.
2026-03-08 19:37:57 +00:00
parent 36252f4ea2
commit 8c136174d1
1 changed files with 181 additions and 1 deletions
--- a/RELOCATION.md
+++ b/RELOCATION.md
@@ -152,8 +152,188 @@ for port in "${PORTS_INTRANET[@]}"; do
    fi
 done

+
+
 echo -e "\n--- Testing Public Ports on $TARGET_IP (von extern prüfen!) ---"
+
 for port in "${PORTS_PUBLIC[@]}"; do
+
    echo "   - Bitte prüfen Sie Port $port manuell von außerhalb des Netzwerks."
+
 done
-```
+
+```
+
+
+
+---
+
+
+
+### **Teil 4: Entwicklungs- vs. Produktions-Workflow**
+
+
+
+Dieses Kapitel definiert die verbindlichen Regeln für die Weiterentwicklung der GTM-Engine nach der Migration, um maximale Stabilität und Sicherheit des Produktivsystems zu gewährleisten.
+
+
+
+#### **1. Grundprinzipien: Getrennte Welten**
+
+
+
+*   **Regel 1: Keine Entwicklung in der Produktion.** Auf der Wackler-VM (`docker1`) wird niemals Code direkt bearbeitet, experimentiert oder getestet. Sie ist ausschließlich für den Betrieb der stabilen Softwareversion vorgesehen.
+
+*   **Regel 2: Getrennte Konfiguration.** Jede Umgebung hat ihre eigene Konfigurationsdatei.
+
+    *   **Produktion (Wackler):** `.env` – Enthält alle echten API-Schlüssel und Endpunkte.
+
+    *   **Entwicklung (Synology):** `.env.dev` (oder eine Kopie der `.env`) – Verwendet Test-Schlüssel, Sandbox-Endpunkte und Dummy-Werte.
+
+*   **Regel 3: Die Produktionsdatenbank ist heilig.** Die produktiven Docker-Volumes (`explorer_db_data` etc.) werden niemals für Entwicklungszwecke angetastet. Lokale Entwicklung findet gegen eine separate, lokale Test-Datenbank statt.
+
+
+
+#### **2. Umgang mit Live-Daten & Aktionen**
+
+
+
+**a) SuperOffice Webhook**
+
+
+
+*   **Problem:** Es darf nur einen aktiven Webhook geben, um Dateninkonsistenzen zu vermeiden.
+
+*   **Lösung:**
+
+    1.  **Produktion:** Der Webhook (`https://<neue-wackler-domain>/connector/webhook`) wird bei SuperOffice registriert. In der `.env` ist das `WEBHOOK_SECRET_TOKEN` gesetzt.
+
+    2.  **Entwicklung:** In der `.env.dev` wird das `WEBHOOK_SECRET_TOKEN` auskommentiert (`#WEBHOOK_SECRET_TOKEN=...`). Der Connector ist somit "taub" für externe Anrufe.
+
+    3.  **Testen in der Entwicklung:** Um realistische Tests durchzuführen, wird eine Umgebungsvariable `LOG_WEBHOOKS=true` im **produktiv-Connector** gesetzt. Dieser schreibt dann den Body jedes eingehenden Webhooks in die Docker-Logs. Diese JSON-Payloads können kopiert werden, um mit einem Skript (`curl`) gezielte, manuelle Tests gegen die lokale Entwicklungsumgebung zu fahren.
+
+
+
+**b) E-Mail-Versand (Lead Engine & Co.)**
+
+
+
+*   **Problem:** Das Entwicklungssystem darf unter keinen Umständen E-Mails an echte Kunden oder Kontakte senden.
+
+*   **Lösung: Der "Safety Override"**
+
+    1.  **Produktion:** Die echten MS Graph API Credentials (`INFO_...`) sind in der `.env` gesetzt.
+
+    2.  **Entwicklung:** Die MS Graph Credentials in der `.env.dev` sind auskommentiert oder mit Dummy-Werten belegt.
+
+    3.  **Sicherer Test-Modus:** Eine neue Umgebungsvariable `DEV_MODE_EMAIL_RECIPIENT` wird implementiert.
+
+        *   Wenn diese Variable in der `.env.dev` gesetzt ist (z.B. `DEV_MODE_EMAIL_RECIPIENT=ihre.test@adresse.de`), leitet der Code **alle** ausgehenden E-Mails an diese eine Adresse um.
+
+        *   **Test-Prozess:** Für einen E-Mail-Test werden in der `.env.dev` temporär die echten MS Graph Credentials eingetragen, `DEV_MODE_EMAIL_RECIPIENT` gesetzt, der Test durchgeführt und danach werden die Credentials **sofort wieder entfernt/auskommentiert**.
+
+
+
+#### **3. Deployment-Prozess: Von der Entwicklung zur Produktion**
+
+
+
+Der Prozess, um neuen, getesteten Code sicher auf das Produktivsystem zu bringen, ist wie folgt:
+
+
+
+1.  **Entwicklung (Synology):**
+
+    *   Ein neues Feature wird entwickelt und lokal gegen die Test-Datenbank getestet.
+
+    *   Änderungen werden committet und in das **lokale Gitea auf der Synology** gepusht (`git push`).
+
+
+
+2.  **Deployment (Wackler VM):**
+
+    *   Verbindung zur Wackler-VM via SSH.
+
+    *   Ins Projektverzeichnis navigieren (`/opt/gtm-engine`).
+
+    *   Den neuesten stabilen Code vom Entwicklungs-Gitea holen: `git pull synology main`.
+
+    *   Die Docker-Container mit dem neuen Code neu bauen und starten: `docker compose up -d --build`.
+
+
+
+3.  **Netzwerkanforderung für Deployment:**
+
+    *   Für den `git pull`-Befehl muss die Wackler-VM (`10.10.81.2`) auf den **Gitea-Port (TCP 3000) der Synology-Diskstation** zugreifen können. Dies muss einmalig im Netzwerk konfiguriert werden.
+
+---
+
+### **Teil 5: Alternative - Single-Host-Setup (Dev & Prod auf einer VM)**
+
+Dieses Szenario beschreibt den wahrscheinlicheren Fall, dass die gesamte Arbeit (Entwicklung und Produktion) auf der von der IT bereitgestellten VM (`docker1`) stattfinden muss. Der Ansatz wandelt sich von "physischer Trennung" zu **"logischer Trennung mit starker Isolation"**.
+
+#### **1. Grundkonzept: Schalldichte Räume**
+
+Auf der VM werden zwei komplett isolierte Umgebungen parallel betrieben. Docker ist für dieses Szenario optimiert und gewährleistet die Trennung von Code, Konfiguration, Ports und vor allem Daten.
+
+*   **Produktionsumgebung (`prod`):** Läuft stabil mit dem geprüften Code und greift auf die produktiven Daten zu.
+*   **Entwicklungsumgebung (`dev`):** Dient zum Entwickeln und Testen. Hat eine eigene Konfiguration und eine komplett separate Test-Datenbank.
+
+#### **2. Implementierung**
+
+**a) Verzeichnisstruktur**
+
+Eine saubere Ordnerstruktur ist die Basis für die Trennung.
+
+```
+/opt/gtm-engine/
+├── dev/
+│   ├── docker-compose.yml
+│   ├── .env
+│   └── (kompletter Code des Projekts...)
+│
+└── prod/
+    ├── docker-compose.yml
+    ├── .env
+    └── (kompletter Code des Projekts...)
+```
+
+**b) Auflösung von Port-Konflikten**
+
+Zwei Stacks können nicht dieselben Ports nutzen. Die `dev`-Umgebung nutzt daher verschobene Ports.
+
+| Dienst | Produktions-Port (in `prod/docker-compose.yml`) | Entwicklungs-Port (in `dev/docker-compose.yml`) |
+| :--- | :---: | :---: |
+| Gateway | `8090:80` | `9090:80` |
+| Webhook | `8003:8003` | `9003:8003` |
+| GTM | `8094:3005` | `9094:3005` |
+
+So ist das **Produktivsystem** unter `http://10.10.81.2:8090` und das **Entwicklungssystem** unter `http://10.10.81.2:9090` erreichbar.
+
+**c) Garantierte Datenbank-Isolation**
+
+**Dies ist der wichtigste Punkt:** Docker stellt sicher, dass die Datenbanken niemals vermischt werden können. Docker Compose erstellt benannte Volumes mit dem Verzeichnisnamen als Präfix.
+
+*   `docker compose up` im Ordner `prod/` erzeugt das Volume `prod_explorer_db_data`.
+*   `docker compose up` im Ordner `dev/` erzeugt das Volume `dev_explorer_db_data`.
+
+Diese beiden Volumes sind **vollständig voneinander isolierte Container** auf der Festplatte. Ein Zugriff von `dev` auf `prod`-Daten ist technisch unmöglich. **Ihre Anforderung, dass die Produktionsdatenbank sicher ist, wird hiermit zu 100% erfüllt.**
+
+#### **3. Vereinfachter Workflow auf einer Maschine**
+
+Das neue Gitea (auf Port 3000) wird zur zentralen "Source of Truth".
+
+1.  **Entwicklung:**
+    *   Sie arbeiten im Verzeichnis `/opt/gtm-engine/dev/`.
+    *   Sie ändern den Code und testen ihn, indem Sie den `dev`-Stack starten:
+        `cd /opt/gtm-engine/dev/ && docker compose up -d --build`
+    *   Sie verifizieren die Änderungen im Browser unter `http://10.10.81.2:9090`.
+    *   Wenn alles passt, committen Sie und pushen zum Gitea auf derselben Maschine: `git push`.
+
+2.  **Deployment (Release in die Produktion):**
+    *   Wechseln Sie in das Produktionsverzeichnis: `cd /opt/gtm-engine/prod/`.
+    *   Holen Sie den neuen, im `dev`-Zweig getesteten Code aus Gitea: `git pull`.
+    *   Aktualisieren Sie den Produktions-Stack: `docker compose up -d --build`.
+
+Dieser Prozess ist sicher, schnell und wiederholbar, da er nur aus Standard-Git- und Docker-Befehlen besteht.
+