Softec-Integration

Der Angebot-Konstruktor ist nahtlos in Fortuna Softec integriert. Sie können direkt aus Softec einsteigen (SSO) und fertige Angebote als Projekte exportieren.

Single Sign-On (SSO)

Mit SSO können Sie den Angebot-Konstruktor direkt aus Fortuna Softec öffnen -- ohne erneute Passworteingabe.

So funktioniert's

1. Loggen Sie sich in Fortuna Softec ein
2. Navigieren Sie zu:
   • Angebote → Button "Tool öffnen", oder
   • Projekt-Details → Button "Angebots-Konstruktor"
3. Ein neuer Tab öffnet sich mit dem Angebot-Konstruktor
4. Sie sind automatisch eingeloggt (SSO-Token)

Popup-Blocker

Der Angebot-Konstruktor öffnet sich in einem neuen Browser-Tab. Falls Ihr Browser Popups blockiert, erlauben Sie Popups für die Fortuna Softec URL. Das System öffnet den Tab zunächst synchron, um Popup-Blocker zu umgehen, und navigiert dann zur SSO-URL.

Technischer Hintergrund

Fortuna Softec                     Angebot-Konstruktor
      │                                    │
      │ 1. User klickt "Öffnen"            │
      │    → Neuer Tab wird sofort         │
      │      geöffnet (about:blank)        │
      │                                    │
      │ 2. POST /api/auth/sso-token        │
      │    → JWT wird generiert (60 Sek)   │
      │                                    │
      │ 3. Tab navigiert zu /sso?token=xxx │
      │──────────────────────────────────>│
      │                                    │
      │                    4. Token wird   │
      │                       validiert    │
      │                                    │
      │                    5. Session      │
      │                       erstellt     │
      │                                    │

Sicherheit

• JWT-basiert: Token ist signiert und nicht manipulierbar
• Kurze Gültigkeit: Token läuft nach 60 Sekunden ab
• Shared Secret: Beide Apps teilen ein kryptografisches Geheimnis
• Einmalverwendung: Token wird nach Verwendung ungültig
• Popup-sicher: Tab wird synchron im Click-Handler geöffnet, dann navigiert

Wer hat Zugriff?

Der SSO-Button und die Angebote-Seite sind nur für Benutzer mit Konstruktor-Berechtigung sichtbar:

Rolle	Zugriff
Admin	Immer (automatisch)
Backoffice	Nur mit aktivierter konstruktor_access Berechtigung
Projektleiter	Kein Zugriff
Mitarbeiter	Kein Zugriff

Die konstruktor_access Berechtigung wird vom Admin in der Benutzerverwaltung vergeben (unter den Benutzer-Berechtigungen).

Export zu Softec

Exportieren Sie fertige Angebote direkt in DIE Bausoftware. Das Angebot wird automatisch als Projekt mit Budget angelegt.

Was wird erstellt?

Was wird erstellt	Beschreibung
Projekt	Neues Projekt mit Angebotsdaten
Budget (Herzstück)	Alle Positionen als Budget-Einträge
Gewerke	Werden zu Budget-Kategorien
Kundendaten	Werden dem Projekt zugeordnet

Export durchführen

Voraussetzungen

1. Ein fertiges Angebot im Angebot-Konstruktor
2. Konfigurierte Softec-Verbindung (siehe Einstellungen)
3. Berechtigung in Fortuna Softec (Admin oder Backoffice mit Konstruktor-Zugriff)

Schritt für Schritt

1. Öffnen Sie das Angebot
2. Klicken Sie auf Zu Softec exportieren
3. Prüfen Sie die Zusammenfassung:
   • Projektname
   • Kunde
   • Anzahl Positionen
   • Gesamtsumme
4. Wählen Sie die Umgebung (Dev oder Prod)
5. Klicken Sie auf Exportieren

Export-Dialog

Im Dialog sehen Sie:

• Projektname: Wird aus Angebot übernommen (editierbar)
• Kunde: Aus Angebotsdaten oder manuell wählen
• Beschreibung: Optionale Projektbeschreibung
• Umgebung: Entwicklung oder Produktion

Was wird übertragen?

Projektdaten

Feld	Quelle
Projektname	Angebots-Titel
Kunde	Angebots-Kunde
Beschreibung	Angebots-Beschreibung
Erstellt am	Export-Datum
Erstellt von	Ihr Benutzer

Budget-Einträge

Jede Angebots-Position wird zu einem Budget-Eintrag:

Angebot	→	Herzstück (Budget)
Positionsnummer	→	Position
Beschreibung	→	Bezeichnung
Menge	→	Soll-Menge
Einheit	→	Einheit
Einzelpreis	→	Soll-EP
Gesamtpreis	→	Soll-Summe

Gewerk-Mapping

Gewerke werden zu Budget-Kategorien:

Angebot                     →  Herzstück
├── Gewerk: Rohbau          →  Kategorie: Rohbau
│   ├── Position 1          →     Budget-Eintrag 1
│   └── Position 2          →     Budget-Eintrag 2
└── Gewerk: Elektro         →  Kategorie: Elektro
    └── Position 3          →     Budget-Eintrag 3

Umgebungswahl

Entwicklung (Dev)

• URL: dev.fortuna-softec.com
• Für Tests und Vorschauen
• Keine Auswirkung auf Produktivdaten

Produktion (Prod)

• URL: app.fortuna-softec.com
• Echte Projekte werden angelegt
• Nur verwenden, wenn Angebot final ist

Achtung

Exporte in die Produktionsumgebung erstellen echte Projekte. Stellen Sie sicher, dass alle Daten korrekt sind.

Atomic Creation

Der Export nutzt "Atomic Creation":

• Projekt und Budget werden in einer Transaktion erstellt
• Bei Fehlern wird nichts angelegt (kein halbes Projekt)
• Entweder vollständiger Erfolg oder vollständiger Abbruch

Konstruktor-Rechnungsmodus

Wenn der Admin die Einstellung experimentalKonstruktorInvoicing aktiviert hat, wird der Angebot-Konstruktor zur zentralen Anlaufstelle für die Rechnungsverwaltung:

Was ändert sich?

Bereich	Ohne Konstruktor-Modus	Mit Konstruktor-Modus
Rechnungen erstellen	In Softec	Im Konstruktor
Rechnungen bearbeiten	In Softec	Im Konstruktor
Rechnungen versenden	In Softec	Im Konstruktor
Mahnungen erstellen	In Softec	Im Konstruktor
Rechnungen einsehen	In Softec	In Softec (Lesemodus)

Mahnwesen (Dunning)

Im Konstruktor-Modus können Mahnungen für überfällige Rechnungen erfasst werden:

• 1. Mahnung (Zahlungserinnerung)
• 2. Mahnung
• 3. Mahnung (letzte Mahnung)

Jede Mahnung wird protokolliert und die Zahlungsfrist um 14 Tage verlängert.

Synchronisation

Rechnungsdaten werden zwischen Konstruktor und Softec synchronisiert:

• Erstellte Rechnungen erscheinen automatisch in Softec
• Zahlungseingänge und Statusänderungen werden übertragen
• In Softec sind Rechnungen im Konstruktor-Modus schreibgeschützt

Fehlerbehandlung

Häufige Fehler

Fehler	Ursache	Lösung
Verbindungsfehler	Keine Verbindung zu Softec	Internet prüfen, Credentials prüfen
Authentifizierung fehlgeschlagen	Falsches Token/Passwort	Einstellungen prüfen
Keine Berechtigung	Benutzer hat keine Rechte	Admin kontaktieren, konstruktor_access prüfen
Projekt existiert	Gleichnamiges Projekt vorhanden	Projektname ändern
SSO nicht konfiguriert	Shared Secret fehlt	Admin: Env-Vars prüfen
Rechnungen blockiert (409)	Konstruktor-Modus aktiv	Rechnungen im Konstruktor bearbeiten

SSO-Fehler beheben

Falls SSO nicht funktioniert:

1. "SSO nicht konfiguriert"

   • SSO_SHARED_SECRET in beiden Apps setzen
   • Beide Apps neu starten/redeployen

2. "Token abgelaufen"

   • Token ist älter als 60 Sekunden
   • Erneut über Softec einsteigen

3. "Ungültiger Token"

   • Shared Secret stimmt nicht überein
   • Gleichen Wert in beiden Apps verwenden

4. Popup blockiert

   • Popup-Blocker für die Softec-URL deaktivieren
   • Alternativ: Konstruktor direkt über URL öffnen

Retry

Bei temporären Fehlern:

1. Warten Sie einige Sekunden
2. Klicken Sie auf Erneut versuchen
3. Bei wiederholtem Fehler: Support kontaktieren

Nach dem Export

In Softec

Nach erfolgreichem Export finden Sie das Projekt in Fortuna Softec:

1. Öffnen Sie Projekte
2. Suchen Sie nach dem Projektnamen
3. Öffnen Sie das Herzstück
4. Alle Budget-Einträge sind vorhanden

Weiterarbeit

Im Herzstück können Sie:

• Positionen weiter bearbeiten
• Ist-Werte erfassen
• Soll-Ist-Vergleich durchführen
• Berichte erstellen

Budget-Re-Import

Wichtig: Bestehende Arbeitsdaten

Wenn Sie ein Budget in ein bestehendes Projekt importieren, das bereits Arbeitsdaten enthält (Zeiteinträge, Ausgaben, Material), greift ein spezielles Migrations-Verfahren.

Das Problem

Ein Projekt kann bereits erfasste Daten haben:

• TimeEntries: Stundenerfassungen der Mitarbeiter
• Expenses: Ausgaben und Materialkosten
• Dokumente: Fotos, Berichte, etc.

Diese Daten sind an Budget-Positionen verknüpft. Wenn Sie ein neues Budget importieren, müssen diese Verknüpfungen erhalten bleiben.

Die Lösung: Automatische Migration

Der Import prüft und migriert automatisch:

Vor Import:
├── Position "Rohbau" (alt)    ← 45 Stundeneinträge verknüpft
├── Position "Elektro" (alt)   ← 12 Stundeneinträge verknüpft
└── Position "Sanitär" (alt)   ← 5 Stundeneinträge verknüpft

Nach Import:
├── Position "Rohbau" (neu)    ← 45 Stundeneinträge migriert
├── Position "Elektro" (neu)   ← 12 Stundeneinträge migriert
├── Position "Sanitär" (neu)   ← 5 Stundeneinträge migriert
└── Position "Malerarbeiten" (neu) ← Neu, keine Daten

Ablauf beim Re-Import

1. Impact-Check

Vor dem Import prüft das System automatisch:

Geprüft	Beschreibung
Bestehende Arbeit	Gibt es TimeEntries, Expenses?
Anzahl Verknüpfungen	Wie viele Einträge sind betroffen?
Matching-Quote	Wie viele Positionen können zugeordnet werden?

2. Warnung mit Statistiken

Sie sehen eine Warnung mit konkreten Zahlen:

Bestehende Daten gefunden

Dieses Projekt enthält bereits:

• 62 Stundeneinträge
• 8 Ausgaben

Diese werden automatisch auf die neuen Budget-Positionen migriert.

3. Bestätigung erforderlich

Sie müssen den Import explizit bestätigen:

• Ich verstehe, dass bestehende Verknüpfungen migriert werden

4. Automatische Migration

Nach Bestätigung führt Softec die Migration durch:

• Positionen werden nach Name/Beschreibung gematcht
• Gefundene Matches werden automatisch verknüpft
• Kein manuelles Eingreifen erforderlich

5. Ergebnis-Zusammenfassung

Nach dem Import sehen Sie das Ergebnis:

Import erfolgreich

• 60 von 62 Verknüpfungen migriert
• 2 Einträge konnten nicht zugeordnet werden

Nicht-gematchte Positionen

Kein Datenverlust

Wenn eine Position nicht gematcht werden kann, werden die Daten NICHT gelöscht. Sie bleiben auf den alten Tasks erhalten.

Was passiert mit nicht-gematchten Einträgen?

Szenario	Verhalten
Position umbenannt	Bleibt auf altem Task, manuell zuordnen
Position gelöscht	Bleibt auf altem Task, sichtbar in Reports
Neue Position	Keine Migration nötig (leer)

Warum so?

• Datenverlust vermeiden: Erfasste Stunden sind wertvoll
• Transparenz: Sie sehen "verwaiste" Einträge in Reports
• Reversibilität: Nichts wird unwiderruflich getrennt
• Kontext erhalten: "Diese Stunden gehörten zu Position X" bleibt sichtbar

Matching-Logik

Positionen werden nach folgenden Kriterien gematcht:

Priorität	Kriterium	Beispiel
1	Exakter Name	"Rohbau" = "Rohbau"
2	Ähnlicher Name	"Rohbau" ~ "Rohbauarbeiten"
3	Positionsnummer	"1.1.10" = "1.1.10"

Best Practices

Für hohe Matching-Quote

1. Positionsnamen beibehalten: Ändern Sie Namen nicht unnötig
2. Struktur beibehalten: Gleiche Gewerke, gleiche Reihenfolge
3. Vor Import prüfen: Schauen Sie sich die Warnung genau an
4. Nach Import prüfen: Kontrollieren Sie die Migration in Reports

Technischer Hintergrund

Die Migration läuft komplett in Softec:

• Single Source of Truth: Softec kennt die Datenstrukturen
• Atomare Transaktion: Entweder komplett oder gar nicht
• Audit-Trail: Alle Migrationen werden protokolliert

Angebot-Konstruktor                    Softec
       │                                  │
       │ 1. GET /check-budget-impact      │
       │─────────────────────────────────>│
       │     { hasWork: true, count: 62 } │
       │<─────────────────────────────────│
       │                                  │
       │ 2. User bestätigt                │
       │                                  │
       │ 3. POST /create-project          │
       │─────────────────────────────────>│
       │                                  │ (Migration läuft)
       │     { migrated: 60, unmatched: 2 }│
       │<─────────────────────────────────│

Synchronisation

Einweg-Export

Der Export ist eine Einweg-Übertragung. Änderungen in Softec werden nicht zurück zum Angebot-Konstruktor synchronisiert (außer bei Rechnungen im Konstruktor-Modus).

Wenn Sie Änderungen am Angebot vornehmen:

1. Bearbeiten Sie das Angebot im Konstruktor
2. Exportieren Sie erneut → Migration greift automatisch
3. Oder: Bearbeiten Sie direkt in Softec

Konfiguration für Administratoren

SSO einrichten

Beide Anwendungen benötigen das gleiche SSO_SHARED_SECRET:

In Fortuna Softec (.env):

SSO_SHARED_SECRET=your-32-byte-secret-here
ANGEBOT_KONSTRUKTOR_URL=https://angebot.fortuna-softec.com

Im Angebot-Konstruktor (.env):

SSO_SHARED_SECRET=your-32-byte-secret-here

Secret generieren

# Auf Mac/Linux:
openssl rand -hex 32

Docker/Dokploy

Bei Docker-Deployments müssen die Env-Vars in der docker-compose.dokploy.yml whitelisted sein:

services:
  app:
    environment:
      SSO_SHARED_SECRET: ${SSO_SHARED_SECRET}
      ANGEBOT_KONSTRUKTOR_URL: ${ANGEBOT_KONSTRUKTOR_URL}

Nach Änderungen: Redeploy erforderlich.