# Systemarchitektur

## Architektur-Uebersicht

```mermaid
graph TB
    subgraph External["Externe Systeme"]
        Bexio["Bexio ERP API"]
        SharePoint["SharePoint Online"]
        Teams["Microsoft Teams"]
    end

    subgraph Integration["Integration Layer"]
        Connector["Custom Connector<br/>BexioV3"]
        Imports["Import/Export<br/>Mechanism"]
    end

    subgraph DataModel["Dataverse Datenmodell"]
        Stamm["Stammdaten<br/>Artikel, Hersteller<br/>Kontakte, Firmen"]
        Inventar["Bestandsdaten<br/>Geraete, Standorte<br/>Business Units"]
        Geschaeft["Geschaeftsdaten<br/>Relationen, Pruefberichte<br/>Zeit-Tracking"]
        Config["Steuerung & Logs<br/>syncconfig<br/>bexiosyncerror"]
    end

    subgraph Automation["Power Automate Flows"]
        SyncKontakte["BexioSynchKontakte<br/>woechentlich"]
        SyncRelation["BexioSynchRelation<br/>taeglich 04:00"]
        MapFlows["Mapping Flows<br/>Artikel, Pruefbericht<br/>Standort, Hersteller"]
        ManualOps["Business Unit<br/>Operationen"]
    end

    subgraph Apps["User-Facing Apps"]
        CanvasMain["Canvas App: bmvcc<br/>Hauptanwendung"]
        CanvasBexio["Canvas App: bexiokontakte<br/>CRM-Fokus"]
        CanvasTest["Canvas App: test1<br/>Prototype"]
        ModelDriven["Model-Driven<br/>Navigation"]
    end

    Bexio -->|REST API| Connector
    Connector -->|Bexio-Daten| SyncKontakte
    Connector -->|Kontakt-Relationen| SyncRelation

    SyncKontakte -->|Create/Update| Stamm
    SyncRelation -->|Create/Update| Geschaeft

    Stamm -->|Referenzen| MapFlows
    Inventar -->|Device Data| MapFlows
    Geschaeft -->|Relations| MapFlows

    MapFlows -->|Updates| Inventar
    MapFlows -->|Updates| Geschaeft

    SyncKontakte -->|Status| Config
    SyncRelation -->|Status & Fehler| Config
    MapFlows -->|Erfolg/Fehler| Config

    Stamm -->|Read| CanvasMain
    Inventar -->|Read| CanvasMain
    Geschaeft -->|Read| CanvasMain
    Config -->|Read| CanvasMain

    Stamm -->|Read| CanvasBexio
    Geschaeft -->|Read| CanvasBexio

    Inventar -->|Read| CanvasTest

    CanvasMain -->|Create/Update| Inventar
    CanvasMain -->|Create/Update| Geschaeft
    CanvasMain -->|Create/Update| Stamm

    CanvasBexio -->|Create/Update| Stamm
    CanvasBexio -->|Create/Update| Geschaeft

    SyncKontakte -->|PostMessage| Teams
    SyncRelation -->|PostMessage| Teams

    Imports -->|CSV/EXCEL| Inventar
    Config -->|Read| Automation
```

## Komponenten im Detail

### Externe Systeme

- **Bexio**: ERP-System, das Kontakt-, Firmen- und Relationsdaten bereitstellt
- **SharePoint**: Optionaler Zielort fuer Datenintegration (via Umgebungsvariable)
- **Microsoft Teams**: Benachrichtigungskanal fuer asynchrone Sync-Status

### Integration Layer

- **Custom Connector BexioV3**: translates REST-API-Aufrufe nach Dataverse
- **Import/Export-Mechanismen**: fuer Bulk-Initialisierung oder Migrationen

### Dataverse Datenmodell

#### Stammdaten-Cluster

- `bmvcc_Artikel`: Produktinformationen
- `bmvcc_Hersteller`: Lieferanten- und Herstellerinformationen
- `bmvcc_Kontakt`: Personenkontakte (hauptsaechlich aus Bexio)
- `bmvcc_firma`: Firmenkontakte (hauptsaechlich aus Bexio)

#### Bestandsdaten-Cluster

- `bmvcc_equipmentrecord`: Geraete und Betriebsmittel
- `bmvcc_organizationlocation`: Standorte und Lagerungen
- `businessunit`: Organizations- und Autorisierungseinheiten

#### Geschaeftsdaten-Cluster

- `bmvcc_relation`: Zuordnungen zwischen Personen und Firmen
- `bmvcc_Pruefbericht`: Inspektionen und Pruefungen
- `bmvcc_timetrackingentry`: Zeit- und Aktivitaetserfassung

#### Steuerungs- und Logging-Cluster

- `bmvcc_syncconfig`: Konfiguration und Status von Synchronisationslaeufen
- `bmvcc_bexiosyncerror`: Fehlerprotokolle fuer Troubleshooting
- `bmvcc_Configuration`, `bmvcc_ConfigurationSetting`: Systemkonfiguration

### Power Automate Flows

#### Geplante Synchronisationen

- **BexioSynchKontakte**: Woechentlich – liest Bexio-Kontakte und Firmen, aktualisiert Dataverse
- **BexioSynchRelation**: Taeglich um 04:00 – liest Bexio-Kontakt-Firma-Beziehungen, aktualisiert `bmvcc_relation`

#### Manuelle Mapping-Flows

- **GeraeteArtikelMapTabelle**: mappt Artikel auf Geraete
- **GeraetePruefberichtMapTabelle(V2)**: verknuepft Pruefberichte mit Geraeten
- **GeraeteStandortMapTabelle**: ordnet Standorte Geraeten zu
- **HerstellerArtikelMapTabelle2**: mappt Hersteller auf Artikel
- **HerstellerBusinessunitsetzen**: setzt Business-Unit-Zuordnungen in Zielumgebungen

### User-Facing Apps

#### Canvas Apps

- **bmvcc**: Hauptanwendung – Zugriff auf alle Datenmodelle, operative Datenpflege
- **bexiokontakte**: Fokussierte CRM-App fuer Firmen und Relationen
- **test1**: Prototyp oder Test-App fuer Geraetedaten

#### Model-Driven Navigation

- **configs**: einfache Navigation auf Konfigurationstabelle
- **kontakte**: einfache Navigation auf Relationstabelle

## Typischer Datenfluss

### Szenario: Kontakt-Synchronisation

1. **Trigger**: Woechentlicher Schedule fuer `BexioSynchKontakte`
2. **Bexio API Call**: Connector ruft Kontakte ueber `Allekontakte`-Operation auf
3. **Dataverse Check**: Flow prueft, welche Kontakte bereits in `bmvcc_Kontakt` vorhanden sind
4. **Upsert**: Neue Kontakte werden angelegt, vorhandene aktualisiert
5. **Status-Schreiben**: Laufstatus und Zeitstempel werden in `bmvcc_syncconfig` geschrieben
6. **Fehler-Logging**: Fehler werden in `bmvcc_bexiosyncerror` protokolliert
7. **Teams-Notification**: optionale Benachrichtigung an ein Team

### Szenario: Benutzer erstellt Geraet in Canvas App

1. **User Action**: Benutzer fuellt Geraete-Formular in `bmvcc`-App aus
2. **Dataverse Record**: neuer Datensatz wird in `bmvcc_equipmentrecord` angelegt
3. **Initial Mapping**: Verweise auf Artikel, Hersteller, Standort werden direkt gesetzt oder leer gelassen
4. **Manual Flow**: Administrator laeuft `GeraeteArtikelMapTabelle` aus
5. **Batch Update**: Flow actualisiert fehlende Artikel-Zuordnungen basierend auf Matching-Logik
6. **View Update**: Benutzer sieht in der App automatic gepflegte Beziehungen

### Szenario: Fehler bei Synchronisation

1. **Connector Fehler**: API-Aufruf schlaegt fehl (z.B. Authentifizierung, Rate Limit)
2. **Error Catch**: Flow traegt Fehler in `bmvcc_bexiosyncerror` ein
3. **Status Update**: `bmvcc_syncconfig` wird mit Fehlerstatus aktualisiert
4. **Teams Alert**: Teams-Benachrichtigung wird gesendet
5. **Manual Review**: Operator prueift das Fehlerprotokoll und triggt ggf. erneuten Lauf

## Skalierungsueberlegungen

- **Datenvolumen**: Flows mit Batch-Request-Logik fuer groessere Datenmengen
- **Trigger-Frequenz**: Geplante Flows laufen zu festen Zeiten; bei Bedarf laufen sie parallel
- **Connection Limits**: Bexio-API hat Ratelimits; Retry-Logik und Paginierung sind wichtig
- **Business Unit Scoping**: nicht alle Flows arbeiten mit globalen Daten; Business-Unit-Filter sind vorhanden

## Deployment-Einheiten

Das Repository enthaelt die gesamte Solution als Einheit. Fuer multi-environment-Deployment sind folgende Items zu beachten:

- Connection References (muessen pro Umgebung neu verlinkt werden)
- Umgebungsvariablen (BusinessUnitId, Dataverse-URL, SharePoint-URL)
- harte URLs in Flows (z.B. in `HerstellerBusinessunitsetzen`)