Quelltext der Seite Intern:Hauptseite/UVdesk

__TOC__

= UVdesk Helpdesk System =

== Übersicht ==
UVdesk ist eine Enterprise-Grade Helpdesk-Lösung, die speziell für die Automatisierung von Support-Prozessen entwickelt wurde. 

=== Der Tech-Stack ===
Das System basiert auf einer modernen PHP-Architektur:
; Framework
: [[Symfony]] (v4.4 / v5.4 LTS)
; Datenbank
: MySQL / MariaDB (Doctrine ORM)
; Template-Engine
: Twig
; Mail-Handling
: Swiftmailer (in neueren Versionen Symfony Mailer)
; Paketverwaltung
: Composer

=== Eigenheiten & Unterschiede zu Standard-Symfony ===
Obwohl UVdesk auf Symfony basiert, gibt es einige architektonische Besonderheiten:
; Bundle-Architektur
: UVdesk ist stark modularisiert. Fast alle Funktionen liegen in separaten Bundles unter {{SMC|vendor/uvdesk/}}.
; Custom Routing
: Die Routing-Logik für Member- und Customer-Bereiche ist eng mit der Datenbank verknüpft.
; Service Decoration
: Viele Kern-Services sind so konzipiert, dass sie durch eigene Implementierungen erweitert werden können.

---

== Initial Setup ==
''Dieser Bereich wird noch ergänzt. Geplante Themen:''
; DB-Init
: Initialisierung der Schemata via Doctrine.
; Admin-Setup
: Ersteinrichtung über die CLI.
; bplaced-Permissions
: Spezifische Rechte für das Temp-Verzeichnis.

---

== How-to's ==
=== Konfiguration der Mailbox ===
''Beschreibung der Anbindung von IMAP/SMTP (iCloud, Office365 etc.)''

---

== Quirks & Fallstricke ==
; Zugehörigkeit
: Achten Sie beim Erstellen von Agents darauf, dass die Rollen-Zuweisung (Role) korrekt erfolgt, da Symfony-Security-Voter den Zugriff steuern.
; Cache-Inkonsistenz
: Nach jeder Änderung an Konfigurationsdateien muss der Symfony-Cache physisch geleert werden (siehe Debugging-Sektion).

---

== Debugging-History ==

Hier werden spezifische Probleme dokumentiert, die in der ArtisanCommerce-Umgebung aufgetreten sind.

=== Fall 01: Swiftmailer Alias & Memory Limit ===
; Datum
: Februar 2026
; Symptom
: {{SMC|cache:clear}} schlägt fehl mit {{SMC|ServiceNotFoundException}} oder {{SMC|Memory Limit Exhausted}}.

==== Lösung A: Swiftmailer Alias Fix ====
In der {{SMC|config/services.yaml}} den Alias manuell setzen:

<syntaxhighlight lang="yaml">
services:
    # Fix für RegisterPluginsPass Bug
    swiftmailer.mailer:
        alias: swiftmailer.mailer.default
        public: true
</syntaxhighlight>

==== Lösung B: Memory Limit via Wrapper ====
; Option 1 (Dauerhaft)
: In der {{SMC|.env}} oder {{SMC|.env.dev}} Variable setzen: {{SMC|MM{{=}}512}}
; Option 2 (CLI)
: Befehl manuell ausführen: {{SMC|MM&equals;512 php bin/console cache:clear}}

=== Fall 02: UVDesk Mailbox / Reply-To Alias Problem ===
; Datum
: Februar 2026
; Symptom
: Beim Refresh der Mailbox schlägt {{SMC|uvdesk:refresh-mailbox}} fehl mit
  {{SMC|Call to a member function getTicket() on null}} in
  {{SMC|MailboxService.php line 516}}.

; Ursache
: UVDesk prüft beim Erstellen eines Tickets die {{SMC|Reply-To}}-Adresse der eingehenden Email
  und versucht, eine passende Mailbox in der Konfiguration zu finden.  
  - Ist die Adresse nicht als Mailbox bekannt, gibt {{SMC|createTicket()}} null zurück → 
    {{SMC|$thread}} wird null → PHP-Fehler beim Aufruf von {{SMC|getTicket()}}.  
  - Dies passiert oft, wenn Kunden an Alias-Adressen wie {{SMC|support@artisancommerce.at}} schreiben, die auf dasselbe IMAP-Postfach {{SMC|artisancommerce@icloud.com}} weitergeleitet werden.

==== Offizieller Ansatz / Best Practice ====
# Für jeden Alias eine eigene Mailbox in UVDesk anlegen:
<syntaxhighlight lang="text">
Name: Support Alias
IMAP Username: artisancommerce@icloud.com
IMAP Passwort: <gleich wie Hauptpostfach>
IMAP Host/Port: <wie Hauptpostfach>
</syntaxhighlight>
: - UVDesk kennt die Adresse → Tickets werden korrekt erstellt.
: - Emails können alle auf dasselbe Postfach zeigen, aber jede Adresse muss als Mailbox konfiguriert sein.

==== Alternative / Quickfix (Patch) ====
# Patch in {{SMC|MailboxService.php}} oder {{SMC|TicketService.php}}:
<syntaxhighlight lang="php">
$mailbox = $this->mailboxService->getMailboxByEmail($ticketData['mailboxEmail']);
if (!$mailbox) {
    $mailboxes = $this->mailboxService->getAllMailboxes();
    $mailbox = reset($mailboxes); // Fallback auf Hauptpostfach
}
</syntaxhighlight>
: - Damit werden alle Emails verarbeitet, auch wenn die Reply-To-Adresse nicht offiziell als Mailbox konfiguriert ist.
: - Tickets werden angelegt, $thread ist nie null, PHP-Fehler entfällt.

==== ASCII-Diagramm: Alias → Postfach → UVDesk ====
<syntaxhighlight lang="text">
Kunde sendet Email
        |
        v
  Reply-To: support@artisancommerce.at
        |
        v
+------------------------+
| IMAP Postfach           |
| artisancommerce@icloud.com
+------------------------+
        ^
        |
  +------------------+
  | UVDesk Mailboxes |
  | ---------------- |
  | support@artisancommerce.at  --> Alias als Mailbox
  | help@artisancommerce.at     --> Alias als Mailbox
  | <Hauptpostfach>             --> Original
  +------------------+
        |
        v
  Ticket / Thread wird erstellt
</syntaxhighlight>
: - Die Mailbox-Zuordnung erfolgt anhand der Reply-To-Adresse.
: - Ohne eingetragene Mailbox → $thread = null → Fehler.

==== Hinweis: IMAP Host / Port / Pfad ====
Beim Einrichten einer UVDesk-Mailbox über IMAP ist nicht nur der Servername entscheidend, sondern auch die **korrekte Pfadangabe für den Posteingang**.

Viele versuchen z. B.:

<syntaxhighlight lang="text">
Host: imap.mail.me.com
Port: 993
SSL: true
</syntaxhighlight>

→ Das funktioniert oft nicht, weil UVDesk intern den **exakten Pfad zum Posteingang** benötigt.

**Besser** ist, den IMAP-Pfad direkt anzugeben, z. B.:

<syntaxhighlight lang="text">
Host: {imap.mail.me.com:993/imap/ssl}INBOX
</syntaxhighlight>

Erklärung in Klartext:  

- `{imap.mail.me.com:993/imap/ssl}` → sagt UVDesk, dass der Server `imap.mail.me.com` auf Port 993 über SSL angesprochen wird.  
- `INBOX` → gibt den **exakten Pfad zum Posteingang** an.  

**Vorteile dieser Struktur:**  
1. UVDesk kann den Posteingang zuverlässig abholen, auch bei Anbietern wie iCloud oder Exchange, die strengere IMAP-Strukturen haben.  
2. Man kann **beliebige Unterordner oder spezielle Mailboxen** angeben, z. B. `Support`, `Tickets`, `Spam`, je nach der Folder-Struktur des IMAP-Postfachs.  
3. Dies erleichtert z. B. Multi-Mailbox-Setups oder die Verarbeitung von automatischen Unterordnern für bestimmte Kunden oder Departments.

**Praktischer Tipp:**  
- Wenn Emails nicht abgeholt werden oder `$thread` null bleibt, immer prüfen, ob der **IMAP Host + Pfad korrekt angegeben** ist.  
- Mit dieser Syntax ist man flexibel und kann mehrere Folder gezielt in UVDesk konfigurieren.

[[Kategorie:Software-Dokumentation]]
[[Kategorie:Helpdesk]]
[[Kategorie:Intern]]