# Automatisiertes Büro 2.0 - Projektdokumentation

## Inhaltsverzeichnis
1. [Projektübersicht](#projektübersicht)
2. [Systemarchitektur](#systemarchitektur)
3. [Entwicklungsumgebung](#entwicklungsumgebung)
4. [Konfigurationen](#konfigurationen)
5. [Installationsanleitung](#installationsanleitung)
6. [Workflows](#workflows)
7. [Sicherheitskonzept](#sicherheitskonzept)
8. [Wartung und Monitoring](#wartung-und-monitoring)
9. [Troubleshooting](#troubleshooting)

## Projektübersicht

### Projektziele
- Vollständige Automatisierung administrativer und kaufmännischer Prozesse
- Kostensenkung durch lokale Open-Source-Lösungen
- Unabhängigkeit von externen Diensten
- Zentralisierte Verwaltung aller Geschäftsprozesse

### Projektumfang
- Integration aller Kommunikationskanäle
- Automatisierte Dokumentenverarbeitung
- Prozessautomatisierung
- Zentrale Authentifizierung
- KI-gestützte Korrespondenz

#### Keycloak-Rolle
Keycloak spielt eine zentrale Rolle als Authentifizierungsstelle. Es stellt die Single-Sign-On (SSO) Funktionalität für alle Dienste der zentralen Plattform bereit und sichert somit den Zugriff auf die verschiedenen Anwendungen.

## Systemarchitektur

#### Architekturübersicht

```mermaid
graph TB
    subgraph Eingangssysteme
        Email[E-Mail]
        WhatsApp[WhatsApp]
        Post[Physische Post]
        Teams[Teams/Webex]
    end

    subgraph Zentrale_Plattform
        NC[Nextcloud - Dokumentenverwaltung]
        PL[Paperless - Dokumentenmanagement]
        NR[Node-RED - Prozessautomatisierung]
        KC[Keycloak - SSO]
        OUI[OpenWebUI - KI-Korrespondenz]
		KI[Kimai - Zeiterfassung]
    end

    subgraph Monitoring_Analytics
        ELK[ELK Stack - Logging & Analyse]
    end

    subgraph Geschäftsprozesse
        TP[Task-Priorisierung]
        subgraph Finanzen
            RE[Rechnungserstellung]
            ZA[Zahlungsabwicklung]
            BA[Banken-API]
        end
        subgraph Verwaltung
            KV[Kundenverwaltung]
            ZE[Zeiterfassung]
            DO[Dokumentenarchiv]
        end
    end

    Email --> NC
    WhatsApp --> NC
    Post --> PL
    Teams --> NC

    NC --> NR
    PL --> NR
    NR --> TP
	KI --> TP

    TP --> RE
    TP --> ZA
    TP --> KV
    TP --> ZE
    TP --> DO

    ZA <--> BA

    KC -.->|Authentifizierung| NC
    KC -.->|Authentifizierung| PL
    KC -.->|Authentifizierung| NR
    KC -.->|Authentifizierung| OUI
	KC -.->|Authentifizierung| KI

    NR --> ELK
    OUI --> NR

    classDef container fill:#e1f5fe,stroke:#01579b
    classDef process fill:#e8f5e9,stroke:#2e7d32
    classDef auth fill:#fff3e0,stroke:#ef6c00
    classDef monitoring fill:#fce4ec,stroke:#c2185b

    class NC,PL,NR,KI container
    class TP,RE,ZA,KV,ZE,DO process
    class KC auth
    class ELK monitoring
```

#### Beschreibung der Architekturkomponenten

Die Systemarchitektur ist in vier Hauptbereiche gegliedert:

1. **Eingangssysteme:**
   - Erfassen verschiedene Kommunikationskanäle zentral.
   - Sorgen für eine einheitliche Weiterverarbeitung aller Eingänge.

2. **Zentrale Plattform:**
   - **Nextcloud (NC):** Dient als zentraler Hub für die Dateiverwaltung und Kollaboration.
   - **Paperless (PL):** Zuständig für das Dokumentenmanagement und die optische Zeichenerkennung (OCR).
   - **Node-RED (NR):** Automatisierung von Workflows und Geschäftsprozessen.
   - **Keycloak (KC):** Bereitstellung von Single-Sign-On (SSO) und Identitätsmanagement.
     - Keycloak wird als zentrale Authentifizierungsstelle für alle Dienste der zentralen Plattform verwendet, wodurch ein sicherer und zentralisierter Zugriff gewährleistet wird.
   -  **OpenWebUI (OUI):** KI-gestützte Kommunikation und Integration in die Workflow-Automatisierung
   -  **Kimai (KI):** Zeiterfassungslösung zur Verwaltung von Arbeitszeiten und Projekten.

3. **Geschäftsprozesse:**
   - Automatisierte Task-Priorisierung (TP) für eine effiziente Aufgabenverteilung.
   - Integrierte Finanzprozesse mit Bankenanbindung (RE, ZA, BA).
   - Zentralisierte Verwaltungsprozesse (KV, ZE, DO).

4. **Monitoring & Analytics:**
   - **ELK Stack (ELK):** Ermöglicht umfassendes Logging und Analyse in Echtzeit zur Überwachung aller Systeme.

#### Containerstruktur
- Docker als Containerisierungsplattform
- Microservices-Architektur
- Interne Netzwerkkonfiguration

### Komponenten
#### Nextcloud
- Funktion: Zentrale Dateiverwaltung und Kollaboration
- Version: `[VERSION]`
- Besondere Konfigurationen:
  - [Wird ergänzt]

#### Paperless
- Funktion: Dokumentenmanagement und OCR
- Version: `[VERSION]`
- Besondere Konfigurationen:
  - [Wird ergänzt]

#### Keycloak
- Funktion: Single-Sign-On und Identitätsmanagement
- Version: `[VERSION]`
- Besondere Konfigurationen:
  - [Wird ergänzt]

#### Node-RED
- Funktion: Workflow-Automatisierung
- Version: `[VERSION]`
- Implementierte Flows:
  - [Wird ergänzt]

#### ELK Stack
- Funktion: Logging und Monitoring
- Version: `[VERSION]`
- Besondere Konfigurationen:
  - [Wird ergänzt]

#### OpenWebUI
- Funktion: KI-gestützte Kommunikation
- Version: `[VERSION]`
- Integrationen:
  - [Wird ergänzt]

#### Kimai
- Funktion: Zeiterfassung
- Version: `[VERSION]`
- Besondere Konfigurationen:
  - [Wird ergänzt]

## Entwicklungsumgebung

### Systemvoraussetzungen
- Windows mit WSL (Windows Subsystem for Linux)
- Visual Studio Code
- Docker Desktop
- NGINX Proxy Manager (läuft in WSL)

#### Domain-Konfiguration
Die Entwicklungsumgebung nutzt die Domain `mrx8086.com` mit verschiedenen Subdomains für die einzelnen Services. Diese werden lokal über die Windows-Hosts-Datei (`C:\Windows\System32\drivers\etc\hosts`) aufgelöst.

```plaintext
# Development Environment Host Entries
127.0.0.1 mrx8086.com
127.0.0.1 proxy.mrx8086.com     # NGINX Proxy Manager
172.23.171.133 auth.mrx8086.com # Keycloak
127.0.0.1 cloud.mrx8086.com     # Nextcloud
127.0.0.1 docs.mrx8086.com      # Paperless
127.0.0.1 time.mrx8086.com      # Kimai
127.0.0.1 automate.mrx8086.com  # n8n
```

#### Service-Übersicht
| Subdomain | Service | Beschreibung |
|-----------|---------|--------------|
| proxy.mrx8086.com | NGINX Proxy Manager | Reverse Proxy und SSL-Management (lokal in der Development Umgebung) |
| auth.mrx8086.com | Keycloak | Zentrale Authentifizierung |
| cloud.mrx8086.com | Nextcloud | Dokumentenverwaltung |
| docs.mrx8086.com | Paperless | Dokumentenmanagement |
| time.mrx8086.com | Kimai | Zeiterfassung |
| automate.mrx8086.com | n8n | Workflow-Automatisierung |

#### WSL-Konfiguration
- NGINX Proxy Manager läuft in WSL
- IP-Adresse des WSL-Systems: 172.23.171.133 (Beispiel, kann sich ändern)
- Alle Docker-Container werden innerhalb von WSL betrieben

#### `setup_realm.js`
Dieses Skript wird verwendet, um den Keycloak-Realm, die zugehörigen Clients und Testbenutzer automatisiert zu erstellen. Es verwendet eine `.env`-Datei zur Konfiguration.

#### Verwendung von .env
Die Konfigurationen für das setup_realm.js Script werden in einer .env Datei gespeichert. Die benötigten Umgebungsvariablen sind unten aufgelistet:
- `KEYCLOAK_URL`: Die URL zum Keycloak Server (z.B. https://auth.mrx8086.com)
- `KEYCLOAK_ADMIN_USER`: Der Benutzername des Keycloak Administrators (z.B. admin).
- `KEYCLOAK_ADMIN_PASSWORD`: Das Passwort des Keycloak Administrators.
- `NEXTCLOUD_CLIENT_ID`: Die Client ID für Nextcloud. (z.B. nextcloud)
- `PAPERLESS_CLIENT_ID`: Die Client ID für Paperless (z.B. paperless).
- `NODERED_CLIENT_ID`: Die Client ID für Node-RED (z.B. nodered).
- `TESTADMIN_PASSWORD`: Das Passwort für den Testadmin User.
- `TESTUSER_PASSWORD`: Das Passwort für den Testuser User.

#### NGINX-Konfigurationen
Für jeden Service existiert eine dedizierte NGINX-Konfiguration. In der Development Umgebung wird der **NGINX Proxy Manager** verwendet. Für **Staging** und **Production** werden die entsprechenden NGINX Konfigurationsdateien in `/config/nginx` abgelegt.

## Konfigurationen

### Netzwerkkonfiguration
- Interne Netzwerkstruktur (noch zu definieren)
- Reverse Proxy Konfiguration über den Nginx Proxy Manager in der Development Umgebung, und Nginx Server Config in Staging und Production.
- SSL/TLS-Setup: Selbsignierte Zertifikate in der Development Umgebung, Letsencrypt in Staging und Production.
- Konfigurationsdateien für NGINX Server Config sind unter `/config/nginx/sites-available/` zu finden.
- Für die Entwicklungsumgebung werden die Konfigurationen über den Nginx Proxy Manager konfiguriert.
- Die SSL Zertifikate für die Development Umgebung werden als selbsignierte Zertifikate generiert und in `/config/nginx/ssl/mrx8086.com/` abgelegt.
- In der Staging und Production Umgebung werden die Zertifikate über Let's Encrypt oder eine andere Zertifizierungsstelle verwaltet.

#### Umgebungsvariablen
Es werden zwei `.env`-Dateien verwendet:
Eine im `docker/` Verzeichnis für die Docker-Konfiguration und eine im `scripts/setup/keycloak/` für das `setup_realm.js`-Skript.

**`docker/.env`:**
- `KEYCLOAK_ADMIN_PASSWORD`: Das Passwort für den Keycloak Admin-Benutzer.
- `KC_DB_USERNAME`: Der Benutzername für die Keycloak-Datenbank.
- `KC_DB_PASSWORD`: Das Passwort für die Keycloak-Datenbank.

**`scripts/setup/keycloak/.env`:**
- `KEYCLOAK_URL`: Die URL zum Keycloak-Server (z.B. `https://auth.mrx8086.com`).
- `KEYCLOAK_ADMIN_USER`: Der Benutzername des Keycloak-Administrators (z.B. `admin`).
- `KEYCLOAK_ADMIN_PASSWORD`: Das Passwort des Keycloak-Administrators (generiert durch das Skript).
- `NEXTCLOUD_CLIENT_ID`: Die Client-ID für Nextcloud (z.B. `nextcloud`).
- `PAPERLESS_CLIENT_ID`: Die Client-ID für Paperless (z.B. `paperless`).
- `NODERED_CLIENT_ID`: Die Client-ID für Node-RED (z.B. `nodered`).
- `TESTADMIN_PASSWORD`: Das Passwort für den Testadmin User.
- `TESTUSER_PASSWORD`: Das Passwort für den Testuser User.

Die Passwörter in der `.env` Datei im `scripts/setup/keycloak` werden vom `setup_environment.sh` Skript generiert.

#### Keycloak-Konfiguration

Keycloak ist als zentrale Authentifizierungsstelle konfiguriert. Die Realm-Konfiguration, Clients und Benutzer werden über das `setup_realm.js` Skript definiert, die Konfiguration wird über die `.env` Datei im `/scripts/setup/keycloak` Verzeichnis angepasst.

##### Realm-Konfiguration
- **Realm-Name:** `office-automation`
- **Anzeige Name:** `Office Automation`
- **SSL ist erforderlich**: `external`
- **Registrierung ist nicht erlaubt**: `false`
- **Login mit Email ist erlaubt**: `true`
- **Doppelte Email ist nicht erlaubt**: `false`
- **Passwort Reset ist erlaubt**: `true`
- **Username Bearbeitung ist nicht erlaubt**: `false`
- **Brute Force Schutz ist aktiviert**: `true`
- **Permanente Sperrung ist nicht aktiviert**: `false`
- **Standard Signature Algorithm**: `RS256`
- **WebAuthn Policy Signatur Algorithmen**: `ES256`
- **WebAuthn Policy Attestation Conveyance Preference**: `none`
- **WebAuthn Policy Authenticator Attachment**: `cross-platform`
- **WebAuthn Policy Require Resident Key**: `not specified`
- **WebAuthn Policy User Verification Requirement**: `preferred`
- **WebAuthn Policy Create Timeout**: `0`
- **WebAuthn Policy Avoid Same Authenticator Register**: `false`
- **Default Default Client Scopes**: `email`, `profile`, `roles`, `web-origins`
- **Default Optional Client Scopes**: `address`, `phone`, `offline_access`, `microprofile-jwt`

##### Clients
Die folgenden Clients werden über das Skript konfiguriert:
- **Nextcloud:**
  -   **Client ID:** `nextcloud`
  -   **Name:** `Nextcloud`
  -   **Redirect URIs:** `https://cloud.mrx8086.com/*`
- **Paperless:**
  -   **Client ID:** `paperless`
  -   **Name:** `Paperless`
  -   **Redirect URIs:** `https://docs.mrx8086.com/*`
- **Node-RED:**
  -   **Client ID:** `nodered`
  -   **Name:** `Node-RED`
  -   **Redirect URIs:** `https://automate.mrx8086.com/*`

##### Gruppen
- **Administrators:** Gruppe für Benutzer mit vollem Systemzugriff.
- **Users:** Gruppe für reguläre Systembenutzer.

##### Benutzer
- **testadmin:**
  - Benutzername: `testadmin`
  - Passwort: wird entweder aus der Umgebungsvariable `TESTADMIN_PASSWORD` gelesen oder standardmäßig `initial123!` gesetzt.
  - Gruppe: `/Administrators`
- **testuser:**
  - Benutzername: `testuser`
  - Passwort: wird entweder aus der Umgebungsvariable `TESTUSER_PASSWORD` gelesen oder standardmäßig `initial123!` gesetzt.
  - Gruppe: `/Users`

#### SSL/TLS-Setup
-   **Entwicklungsumgebung (`dev`):** Für lokale Entwicklung werden selbsignierte SSL-Zertifikate verwendet.
-   **Staging/Produktionsumgebung (`staging`, `production`):** Hier werden SSL-Zertifikate über Let's Encrypt oder eine ähnliche Zertifizierungsstelle verwaltet.

## Installationsanleitung
#### Voraussetzungen
- Docker Version: `[VERSION]`
- Minimal Systemanforderungen:
  - CPU: `[ANFORDERUNG]`
  - RAM: `[ANFORDERUNG]`
  - Speicher: `[ANFORDERUNG]`
- Für die Ausführung des `setup_realm.js` Skriptes wird `Node.js` benötigt
- Die genaue Version von `Node.js` wird zu einem späteren Zeitpunkt dokumentiert.
- Vor dem starten müssen die Passwörter generiert und die `.env` Dateien erstellt werden. Hierzu wird das `setup_environment.sh` verwendet. Dieses Skript sollte **nicht in der Produktionsumgebung** verwendet werden.
- Das Skript erstellt die benötigten Verzeichnisse, generiert zufällige Passwörter, speichert diese verschlüsselt ab, und erstellt die benötigten `.env` Dateien.
- Für die Ausführung des `setup_realm.js` Skriptes wird `Node.js` und `npm` benötigt
- Die benötigten Node Module `dotenv` und `axios` können mit `npm install dotenv axios` installiert werden.
- Die `.env` Dateien werden im `/docker` und im `/scripts/setup/keycloak` Verzeichnis abgelegt.

#### Keycloak-Installation
1.  Führe das `setup_environment.sh` Skript aus, um die .env Dateien, die Passwörter zu generieren und die Credentials zu verschlüsseln.
2.  Kopiere die `docker-compose.yml` Datei in das `docker/` Verzeichnis.
3.  Kopiere die `.env` Datei in das `docker/` Verzeichnis.
4.  Führe `docker-compose up -d` im `docker/` Verzeichnis aus um Keycloak zu starten.

#### Ausführen von `setup_realm.js`
1.  Stelle sicher, dass Node.js und npm installiert sind.
2.  Wechsle in das `/scripts/setup/keycloak` Verzeichnis.
3.  Installiere die benötigten npm Pakete mit `npm install dotenv axios`.
4.  Führe das Skript mit `node setup_realm.js` aus. Dies erstellt den Keycloak-Realm, die Clients und die Testbenutzer.
    * Das Script befindet sich im `/scripts/setup/keycloak` Verzeichnis

## Workflows
#### Dokumentenverarbeitung
- Eingangsverarbeitung
- OCR-Prozess
- Kategorisierung
- Archivierung

#### Geschäftsprozesse
- Rechnungsstellung
- Zahlungsabwicklung
- Kundenmanagement
- Zeiterfassung

#### Authentifizierungsflow
Die Authentifizierung der Benutzer für alle Dienste wird über Keycloak abgewickelt. Details zu den Authentifizierungsabläufen werden in einem späteren Schritt dokumentiert.

## Sicherheitskonzept
#### Zugriffsmanagement
- Rollenkonzept (wird in späteren schritten dokumentiert)
- Berechtigungsmatrix (wird in späteren schritten dokumentiert)
- Authentifizierungsflows (siehe Workflows)
- Keycloak wird als zentrale Authentifizierungsstelle verwendet, Passwortrichtlinien werden in Keycloak definiert.

#### Datensicherheit
- Verschlüsselung (wird in späteren schritten dokumentiert)
- Backup-Strategie (wird in späteren schritten dokumentiert)
- Notfallwiederherstellung (wird in späteren schritten dokumentiert)

## Wartung und Monitoring
#### Regelmäßige Wartungsaufgaben
- Backup-Überprüfung
- Updates
- Performance-Monitoring

Details zur Wartung und dem Monitoring werden in späteren Schritten dokumentiert.

## Troubleshooting
#### Bekannte Probleme
- [Wird ergänzt mit auftretenden Problemen]

#### Debugging
- Log-Analyse
- Fehlerbehandlung
- Support-Prozesse
Details zu bekannten Problemen und zur Fehlerbehandlung werden in späteren Schritten dokumentiert.