Add Alphaplan discovery exporter and finance docs

TrafagSalesExporter/docs/ALPHAPLAN_DISCOVERY_EXPORTER_GUIDE_2026-06-08.md

@@ -0,0 +1,270 @@
+# Alphaplan Discovery Exporter Guide
+
+Stand: 2026-06-08
+
+Zweck: Diese Anleitung dokumentiert das Phase-1-Paket fuer Deutschland/Alphaplan. Das Paket soll auf dem deutschen Alphaplan-/SQL-Server laufen, relevante SQL-Datenbanken, Tabellen und Views finden, CSV-Dateien erzeugen und diese optional per `rclone` nach SharePoint laden.
+
+## Status
+
+- Paket erstellt: `AlphaplanExportPackage`.
+- ZIP erstellt: `AlphaplanExportPackage.zip`.
+- Phase: Discovery / Rohdatenanalyse.
+- BiDashboard-Import wird dadurch noch nicht angepasst.
+- BiDashboard-App-Code wird fuer diesen Exporter nicht benoetigt.
+- PowerShell-Syntax des Scripts wurde lokal geprueft.
+
+## Dateien
+
+| Datei | Zweck |
+| --- | --- |
+| `AlphaplanExportPackage/Run-AlphaplanDiscoveryAndUpload.ps1` | All-in-one Discovery, optional Samples, optional rclone Upload |
+| `AlphaplanExportPackage/README.txt` | Kurzanleitung fuer den DE-Server |
+| `AlphaplanExportPackage.zip` | Kopierbares Paket fuer den DE-Server |
+| `docs/ALPHAPLAN_SQL_RCLONE_KONZEPT_DE_2026-06-08.md` | Fach-/Technikkonzept |
+| `docs/ALPHAPLAN_DISCOVERY_EXPORTER_GUIDE_2026-06-08.md` | Diese Nachdokumentation |
+
+## Zielbild
+
+Der Export laeuft direkt auf dem Alphaplan-Server in Deutschland:
+
+1. PowerShell startet das Script.
+2. Script verbindet sich read-only mit SQL Server.
+3. Script scannt SQL-Datenbanken, Tabellen und Views.
+4. Script bewertet Kandidaten anhand von Namen und Spalten.
+5. Script schreibt `candidate_objects.csv`.
+6. Script schreibt `export_summary.csv`.
+7. Optional schreibt es kleine `sample_*.csv`.
+8. Optional laedt `rclone` die Dateien nach SharePoint.
+
+## SharePoint-Ziel
+
+Default:
+
+```text
+trafag-bi:Import/Finance/Deutschland/AlphaplanRaw
+```
+
+Dieser Rohdatenordner ist bewusst getrennt vom produktiven Deutschland-Import. So koennen die Discovery-CSV nicht versehentlich vom bestehenden Import als finale Finance-Dateien gelesen werden.
+
+## Lokaler Zielordner auf dem DE-Server
+
+Default:
+
+```text
+C:\Trafag\AlphaplanExport
+```
+
+Unterordner:
+
+```text
+C:\Trafag\AlphaplanExport\out
+C:\Trafag\AlphaplanExport\logs
+```
+
+Pro Lauf entsteht:
+
+```text
+C:\Trafag\AlphaplanExport\out\Alphaplan_SQL_Discovery_YYYYMMDD_HHMMSS
+```
+
+## Ergebnisdateien
+
+| Datei | Inhalt |
+| --- | --- |
+| `candidate_objects.csv` | Relevante SQL-Tabellen/Views mit Score, Spalten, Datums-/Betrags-/Key-Kandidaten |
+| `export_summary.csv` | Status pro Datenbank und optional pro Sample-Export |
+| `README.txt` | Laufbezogene Kurzbeschreibung |
+| `sample_*.csv` | Optionale kleine Beispielauszuege aus Top-Kandidaten |
+
+## Bewertung der Kandidaten
+
+Das Script bewertet Tabellen/Views ueber Objekt- und Spaltennamen. Treffer gibt es u. a. fuer:
+
+- Rechnung, Faktura, Invoice, Beleg
+- Umsatz, Verkauf, Sales, Revenue
+- Position, Zeile, Line
+- Auftrag, Order
+- Kunde, Debitor, Customer, Adresse
+- Artikel, Material, Item, Produkt
+- Betrag, Netto, Umsatz, Amount, Price, Preis, Summe
+- Menge, Anzahl, Quantity, Qty
+- Waehrung, Currency
+- Warengruppe, Produktgruppe
+- Gutschrift, Storno, Credit
+
+Die Discovery ist kein finaler Beweis, sondern eine Vorauswahl fuer DE/IT und Finance.
+
+## Wichtige Parameter
+
+| Parameter | Default | Zweck |
+| --- | --- | --- |
+| `-ServerInstance` | `localhost` | SQL Server / Instanz |
+| `-Database` | leer | leer = alle erreichbaren User-Datenbanken scannen |
+| `-SqlCredential` | leer | optional SQL-Login statt Windows Integrated |
+| `-BaseDirectory` | `C:\Trafag\AlphaplanExport` | lokaler Arbeitsordner |
+| `-MaxCandidatesPerDatabase` | `80` | maximale Kandidaten je Datenbank |
+| `-ExportSamples` | aus | kleine Beispiel-CSV erzeugen |
+| `-MaxSampleObjects` | `15` | maximale Sample-Objekte |
+| `-SampleRows` | `200` | Zeilen pro Sample |
+| `-SkipUpload` | aus | nur lokal erzeugen, kein rclone Upload |
+| `-RcloneExe` | `C:\Tools\rclone.exe` | bevorzugter rclone Pfad |
+| `-RcloneRemote` | `trafag-bi` | rclone Remote |
+| `-RcloneTarget` | `Import/Finance/Deutschland/AlphaplanRaw` | SharePoint-Zielpfad |
+
+## Standardlauf lokal ohne Upload
+
+Auf dem DE-Server im Paketordner:
+
+```powershell
+Set-ExecutionPolicy -Scope Process Bypass
+.\Run-AlphaplanDiscoveryAndUpload.ps1 -SkipUpload
+```
+
+Das ist der empfohlene erste Test, weil keine SharePoint-/rclone-Abhaengigkeit geprueft werden muss.
+
+## Standardlauf mit Upload
+
+```powershell
+Set-ExecutionPolicy -Scope Process Bypass
+.\Run-AlphaplanDiscoveryAndUpload.ps1
+```
+
+Das Script prueft/erstellt das SharePoint-Ziel mit `rclone mkdir`, laedt CSV/TXT hoch und verifiziert danach `candidate_objects.csv` per `rclone lsf`.
+
+## Lauf fuer bekannte Datenbank
+
+Wenn der Alphaplan-Datenbankname bekannt ist:
+
+```powershell
+.\Run-AlphaplanDiscoveryAndUpload.ps1 -Database "ALPHAPLAN"
+```
+
+Wenn die SQL-Instanz nicht `localhost` ist:
+
+```powershell
+.\Run-AlphaplanDiscoveryAndUpload.ps1 -ServerInstance "SERVERNAME\INSTANCE" -Database "ALPHAPLAN"
+```
+
+## Lauf mit Samples
+
+```powershell
+.\Run-AlphaplanDiscoveryAndUpload.ps1 -Database "ALPHAPLAN" -ExportSamples
+```
+
+Samples sind auf `TOP 200` pro Objekt limitiert. Sie helfen Andreas/DE IT, die Inhalte der Top-Kandidaten schnell zu beurteilen.
+
+## SQL Authentifizierung
+
+Windows Integrated ist Default. Fuer SQL-Login:
+
+```powershell
+$cred = Get-Credential
+.\Run-AlphaplanDiscoveryAndUpload.ps1 -ServerInstance "SERVERNAME\INSTANCE" -Database "ALPHAPLAN" -SqlCredential $cred
+```
+
+Empfohlen ist ein read-only Benutzer oder Windows-Servicekonto.
+
+## rclone Voraussetzungen
+
+`rclone` muss auf dem DE-Server eingerichtet sein.
+
+Erwarteter Remote-Name:
+
+```text
+trafag-bi
+```
+
+Der Remote soll auf die Dokumentbibliothek `Shared Documents` dieser Site zeigen:
+
+```text
+https://trafagag.sharepoint.com/sites/WorldwideBIPlatform
+```
+
+Tests:
+
+```powershell
+rclone lsd trafag-bi:
+rclone lsd trafag-bi:"Import/Finance"
+rclone lsd trafag-bi:"Import/Finance/Deutschland"
+```
+
+Das Script sucht `rclone` automatisch an diesen Stellen:
+
+```text
+- Parameter -RcloneExe
+- rclone.exe im Scriptordner
+- C:\Tools\rclone.exe
+- C:\Tools\rclone\rclone.exe
+- C:\Tools\rclone\rclone\rclone.exe
+- rclone aus PATH
+```
+
+## Firewall und Berechtigungen
+
+Vom DE-Server benoetigt:
+
+- SQL Zugriff auf die lokale/interne Alphaplan-Datenbank.
+- Ausgehend TCP 443 zu Microsoft 365/SharePoint fuer `rclone`.
+- Bei Erstkonfiguration optional Browser-/Device-Login fuer Microsoft 365.
+
+Vom BiDashboard-Server benoetigt:
+
+- Kein direkter SQL-Zugriff auf Alphaplan fuer Phase 1.
+
+SQL-Rechte:
+
+- read-only
+- idealerweise Zugriff nur auf benoetigte Datenbanken, Tabellen oder Views
+- keine Schreibrechte
+
+## Abgrenzung zum finalen Import
+
+Phase 1 erzeugt noch kein finales Finance-Format. Ziel ist nur:
+
+- richtige Datenbanken finden
+- relevante Tabellen/Views finden
+- Feldnamen und Beziehungen erkennen
+- Beispiele fuer Andreas/DE IT bereitstellen
+
+Der spaetere Import kann danach auf eine finale SQL-View oder ein gemapptes CSV umgestellt werden. Empfohlene finale View:
+
+```text
+vw_BiDashboard_FinanceSales_DE
+```
+
+## Checkliste fuer DE/IT
+
+Nach dem ersten Discovery-Lauf bitte pruefen:
+
+- Welche Datenbank ist Alphaplan produktiv?
+- Welche Tabelle/View ist Rechnungs-Kopf?
+- Welche Tabelle/View ist Rechnungs-Position?
+- Wie werden Kopf und Position verbunden?
+- Welche Spalte ist Rechnungsnummer?
+- Welche Spalte ist Positionsnummer?
+- Welche Spalte ist Rechnungsdatum oder Buchungsdatum?
+- Welche Spalte ist Nettoumsatz auf Positionsebene?
+- Welche Spalte ist Menge?
+- Welche Spalte ist Artikel-/Materialnummer?
+- Welche Spalten enthalten Kundenname, Kundennummer und Kundenland?
+- Wie erkennt man Gutschriften?
+- Wie erkennt man Stornos?
+- Gibt es eine Aenderungs-/Erfassungsdatumsspalte fuer Delta?
+
+## Bekannte Grenzen
+
+- Discovery erkennt Kandidaten heuristisch anhand von Namen. Tabellen mit neutralen Alphaplan-Namen koennen fehlen.
+- Wenn SQL-Rechte zu eng sind, sind die CSV leer oder unvollstaendig.
+- `RowCountEstimate` ist eine SQL-Server-Schaetzung aus Partition-Stats.
+- Sample-Dateien sind nur Auszuege und nicht fuer Summenabgleich geeignet.
+- Der Upload prueft aktuell `candidate_objects.csv`, nicht jede einzelne Sample-Datei.
+
+## Naechster Schritt
+
+1. ZIP auf DE-Server kopieren.
+2. Discovery lokal ohne Upload ausfuehren.
+3. `candidate_objects.csv` pruefen.
+4. Discovery mit Upload ausfuehren.
+5. Andreas/DE IT markiert die relevanten Alphaplan-Objekte.
+6. Danach wird der finale Alphaplan-Finance-Export oder die Importanpassung definiert.
+

TrafagSalesExporter/docs/ALPHAPLAN_SQL_RCLONE_KONZEPT_DE_2026-06-08.md

@@ -0,0 +1,203 @@
+# Alphaplan SQL/rclone Konzept Deutschland
+
+Stand: 2026-06-08
+
+Ziel: Auf dem deutschen Alphaplan-Server sollen SQL-Tabellen oder Views direkt als CSV exportiert und anschliessend mit `rclone` nach SharePoint hochgeladen werden. Der BiDashboard-/Finance-Import wird danach separat angepasst. Es werden in diesem Konzept keine Programmcode-Aenderungen am BiDashboard beschrieben.
+
+## Umsetzungsstand 2026-06-08
+
+- Phase-1-Discovery-Paket erstellt: `AlphaplanExportPackage`.
+- Kopierbares ZIP erstellt: `AlphaplanExportPackage.zip`.
+- Hauptscript: `AlphaplanExportPackage/Run-AlphaplanDiscoveryAndUpload.ps1`.
+- Kurzanleitung im Paket: `AlphaplanExportPackage/README.txt`.
+- Detailanleitung: `docs/ALPHAPLAN_DISCOVERY_EXPORTER_GUIDE_2026-06-08.md`.
+- Status: PowerShell-Syntax lokal geprueft; noch kein Lauf auf dem deutschen Alphaplan-Server.
+- Abgrenzung: Noch keine BiDashboard-Importanpassung und kein produktiver Deutschland-Import aus Alphaplan-Rohdaten.
+
+## Kurzfazit
+
+- Der Export soll auf dem Alphaplan-/SQL-Server in Deutschland laufen, nicht auf dem BiDashboard-Server.
+- Der erste Schritt ist bewusst ein Rohdaten-Export von ausgewaehlten SQL-Tabellen oder Views.
+- Upload erfolgt analog Spanien mit `rclone` nach SharePoint.
+- Fuer Rohdaten sollte ein eigener SharePoint-Unterordner verwendet werden, damit der aktuelle Deutschland-Import nicht versehentlich falsche CSV-Dateien einliest.
+- Spaeter kann aus den erkannten Alphaplan-Tabellen eine stabile Finance-Export-View oder ein finaler gemappter CSV-Export entstehen.
+
+## Annahmen
+
+- Alphaplan verwendet Microsoft SQL Server oder eine SQL-Server-kompatible Datenbank.
+- Das Export-Script laeuft lokal auf dem deutschen Server mit Zugriff auf die Alphaplan-Datenbank.
+- Der Export benoetigt nur Leserechte.
+- `rclone` ist auf dem deutschen Server installiert und fuer die SharePoint-Dokumentbibliothek konfiguriert.
+
+## Zielbild Datenfluss
+
+1. Windows Task Scheduler startet das Alphaplan-Export-Script auf dem DE-Server.
+2. Das Script verbindet sich lokal oder intern mit der Alphaplan-SQL-Datenbank.
+3. Das Script exportiert definierte Tabellen/Views als CSV in einen lokalen Laufordner.
+4. Das Script erstellt eine Summary-Datei mit Server, Datenbank, exportierten Objekten, Zeilenanzahl und Fehlern.
+5. `rclone` prueft oder erstellt den SharePoint-Zielordner.
+6. `rclone` laedt CSV und Summary nach SharePoint hoch.
+7. Der BiDashboard-Import wird spaeter auf diese SharePoint-Dateien angepasst.
+
+## SharePoint-Ziel
+
+Empfohlen fuer Rohdaten:
+
+`trafag-bi:Import/Finance/Deutschland/AlphaplanRaw`
+
+Begruendung:
+
+- Der aktuelle Deutschland-Import kann weiterhin unveraendert bleiben.
+- Rohdaten-CSV aus Tabellen/Views haben noch nicht zwingend das finale Finance-Spaltenformat.
+- Wenn der Import spaeter fertig ist, kann das Ziel entweder direkt weiterverwendet oder auf `Import/Finance/Deutschland` umgestellt werden.
+
+Fuer einen spaeteren finalen Finance-CSV-Export waere passend:
+
+`trafag-bi:Import/Finance/Deutschland`
+
+## Export-Phasen
+
+### Phase 1: Discovery
+
+Ziel: Herausfinden, welche Alphaplan-Datenbanken, Tabellen und Views relevant sind.
+
+Ergebnisdateien:
+
+- `candidate_objects.csv`
+- `export_summary.csv`
+- optional kleine Beispiel-CSV je Kandidat
+
+Kandidaten sollten anhand von Namen und Spalten gefunden werden, z. B.:
+
+- Rechnung / Faktura / Beleg
+- Auftrag / Lieferschein
+- Position / Zeile
+- Kunde / Adresse
+- Artikel / Material
+- Warengruppe / Produktgruppe
+- Menge / Preis / Netto / Umsatz
+- Datum / Belegdatum / Rechnungsdatum
+
+### Phase 2: Rohdaten-Export
+
+Ziel: Ausgewaehlte Alphaplan-Tabellen oder Views komplett oder zeitlich gefiltert exportieren.
+
+Typische Exportdateien:
+
+- `Alphaplan.<schema>.<table>.csv`
+- `Alphaplan.<schema>.<view>.csv`
+- `export_summary.csv`
+
+Die Dateien muessen noch nicht dem Finance-Importformat entsprechen. Wichtig ist, dass Andreas/IT daraus die richtigen Tabellen, Schluessel und Felder erkennen kann.
+
+### Phase 3: Finaler Finance-Export
+
+Ziel: Sobald die Tabellenbeziehungen klar sind, wird eine stabile SQL-View oder ein finaler Query definiert, der direkt Finance-taugliche Spalten liefert.
+
+Empfohlen ist eine read-only View, z. B.:
+
+`vw_BiDashboard_FinanceSales_DE`
+
+Diese View sollte pro Rechnungsposition eine Zeile liefern. Dann bleibt das Export-Script einfach und stabil, auch wenn Alphaplan intern mehrere Tabellen benoetigt.
+
+## Benoetigte Informationen von Deutschland/IT
+
+- SQL Server Hostname/Instanz.
+- Datenbankname.
+- Authentifizierung: Windows Integrated oder SQL User.
+- Read-only Benutzer oder Service Account.
+- Liste relevanter Tabellen/Views fuer Rechnungen und Rechnungspositionen.
+- Datumsspalte fuer Voll-/Delta-Export.
+- Kennzeichen fuer Rechnung, Gutschrift, Storno.
+- Waehrungsfeld und Standardwaehrung.
+- Netto-Umsatzfeld auf Positionsebene.
+- Artikelnummer/Materialnummer.
+- Kundenland und Kundenname.
+- Produktgruppe/Warengruppe, falls in Alphaplan vorhanden.
+
+## Minimal benoetigte Finance-Felder spaeter
+
+Fuer den spaeteren Import reichen als Startpunkt:
+
+| Zielfeld | Bedeutung |
+| --- | --- |
+| `TSC` | `TRDE` |
+| `Land` | `Deutschland` |
+| `SourceSystem` | `Alphaplan` |
+| `InvoiceNumber` | Rechnungsnummer |
+| `PositionOnInvoice` | Positionsnummer |
+| `Material` | Artikel-/Materialnummer |
+| `Name` | Artikeltext |
+| `Quantity` | Menge |
+| `CustomerNumber` | Kundennummer |
+| `CustomerName` | Kundenname |
+| `CustomerCountry` | Kundenland |
+| `SalesPriceValue` | Nettoumsatz Positionszeile |
+| `SalesCurrency` | Umsatzwaehrung |
+| `PostingDate` | Buchungs-/Belegdatum |
+| `InvoiceDate` | Rechnungsdatum |
+| `DocumentType` | Rechnung/Gutschrift/Storno |
+
+Weitere Felder wie Warengruppe, Lieferant, Incoterms, Auftrag, Branche und Kosten koennen spaeter ergaenzt werden.
+
+## Delta oder Vollfile
+
+Fuer den Anfang ist ein Vollfile pro Jahr am einfachsten:
+
+- weniger Risiko bei geaenderten oder stornierten Belegen
+- einfacher Abgleich gegen Alphaplan
+- Import kann pro Standort/Jahr neu aufgebaut werden
+
+Delta ist erst sinnvoll, wenn klar ist:
+
+- welche Spalte neue/geaenderte Datensaetze erkennt
+- wie Stornos und Korrekturen geliefert werden
+- ob der Import vorhandene DE-Daten mergen oder ersetzen soll
+
+Wichtig: Wenn der aktuelle Import Standortdaten komplett ersetzt, darf kein kleines Delta so importiert werden, als waere es ein Vollbestand.
+
+## Sicherheit und Firewall
+
+Da der Export auf dem deutschen Alphaplan-Server laeuft, muss der BiDashboard-Server keinen direkten SQL-Zugriff auf Alphaplan bekommen.
+
+Benoetigt auf dem DE-Server:
+
+- SQL Zugriff lokal/intern auf Alphaplan.
+- Ausgehend HTTPS/TCP 443 zu Microsoft 365/SharePoint fuer `rclone`.
+- Optional Zugriff fuer rclone OAuth/Device Login bei der Erstkonfiguration.
+
+SQL Benutzer:
+
+- nur read-only
+- keine Schreibrechte
+- idealerweise Zugriff nur auf benoetigte Views oder Tabellen
+
+## Betrieb
+
+Empfohlener lokaler Ordner auf dem DE-Server:
+
+`C:\Trafag\AlphaplanExport`
+
+Unterordner:
+
+- `out` fuer CSV-Exports
+- `logs` fuer Script- und rclone-Logs
+
+Empfohlener Task:
+
+- taeglich frueh morgens
+- zuerst Voll-/Jahresfile, spaeter optional Range
+- Exitcode und Logdatei pruefen
+- Upload per `rclone lsf` verifizieren
+
+## Abnahmekriterien
+
+Der technische Export gilt als bereit, wenn:
+
+- Discovery-Datei mit Kandidatentabellen/Views auf SharePoint liegt.
+- Mindestens ein relevanter Tabellen-/View-Export auf SharePoint liegt.
+- Summary-Datei Zeilenanzahl und Quelle zeigt.
+- rclone Upload im Log ohne Fehler abgeschlossen ist.
+- Deutschland/IT bestaetigt, welche Tabellen/Views fuer Finance korrekt sind.
+
+Der Finance-Import ist danach ein separater Schritt.

TrafagSalesExporter/docs/FINANCE_DATENFLUSS_ANDREAS_2026-06-08.md

@@ -0,0 +1,461 @@
+# Finance Datenfluss fuer Andreas
+
+Stand: 2026-06-08
+
+Zweck: Diese Notiz beschreibt den tatsaechlichen technischen Datenfluss im Finance Cockpit: wo Daten geholt werden, wann Felder veraendert werden, wann Wechselkurse wirken, wie die zentrale Excel entsteht und welche Quelle die Sparteninformationen liefert.
+
+## Kurzfazit
+
+- Finance Summary, Management Analyse und Spartenanalyse lesen nicht aus dem SharePoint-Excel, sondern direkt aus der App-Datenbank `CentralSalesRecords`.
+- Das SharePoint-Excel `Sales_All_*.xlsx` ist ein Export-/Ablageergebnis, nicht die Live-Quelle der Cockpit-Anzeige.
+- Jeder Standortexport ersetzt in `CentralSalesRecords` nur die Daten dieses Standorts.
+- Die zentrale Excel wird danach aus dem aktuellen Stand von `CentralSalesRecords` erzeugt.
+- Wechselkurse veraendern den Standortexport und `CentralSalesRecords` normalerweise nicht. Sie wirken in Analyse-/Anzeige-Sichten, wenn eine Zielwaehrung wie CHF/EUR/USD ausgewaehlt ist, oder in explizit konfigurierten Transformationen.
+- Sparteninformationen kommen fuehrend aus SAP/TR-AG `ProductDivisionRefSet`. Aktuell werden sie beim ZSCHWEIZ-/CH-/AT-Export direkt mitgeladen. Andere Laender werden in der Analyse ueber ihre Materialnummer gegen diese TR-AG-Referenz gematcht.
+
+## Technischer Ablauf Standortexport
+
+Ausloeser:
+
+- Export Dashboard: einzelner Standort oder `Alle exportieren`.
+- Timer, falls aktiv.
+- Intern: `ExportOrchestrationService` ruft `SiteExportService.ExportAsync(...)`.
+
+Ablauf pro Standort:
+
+1. Standort und Quellsystem werden geladen.
+2. Adapter wird nach `ConnectionKind` gewaehlt:
+   - `HanaDataSourceAdapter` fuer BI1/HANA.
+   - `SapGatewayDataSourceAdapter` fuer SAP OData.
+   - `ManualExcelDataSourceAdapter` fuer Excel/CSV/SharePoint-Dateien.
+3. Rohdaten werden als `SalesRecord`-Liste aufgebaut.
+4. Aktive `FieldTransformationRules` fuer das Quellsystem werden angewendet.
+5. Eine lokale Standort-Excel `Sales_<TSC>_<Datum>.xlsx` wird erzeugt.
+6. `CentralSalesRecords` wird fuer diesen Standort ersetzt:
+   - alte Saetze mit `SiteId = Standort` loeschen.
+   - neue Saetze einfuegen.
+7. Falls SharePoint komplett konfiguriert ist, wird die Standort-Excel nach SharePoint hochgeladen.
+
+Wichtig: Die Reihenfolge ist zuerst Daten holen, dann Transformationen, dann lokale Excel, dann zentrale Tabelle, dann SharePoint-Upload. Der SharePoint-Upload entscheidet nicht, was in der Cockpit-Anzeige erscheint.
+
+## Datenquellen pro Quelltyp
+
+### HANA / SAP B1
+
+Betroffen:
+
+| Land | TSC | Schema | Quelle |
+| --- | --- | --- | --- |
+| Frankreich | `TRFR` | `fr01_p` / lokal teils `FR01_p` | BI1/HANA |
+| Italien | `TRIT` | `it01_p` | BI1/HANA |
+| USA | `TRUS` | `us01_p` | BI1/HANA |
+| Indien | `TRIN` | `TRAFAG_LIVE` | HANA/Sage-Quelle |
+
+Standard-B1-Abfrage:
+
+- Rechnungen aus `OINV` + `INV1`.
+- Gutschriften aus `ORIN` + `RIN1`.
+- Stornierte Belege werden ausgeschlossen: `CANCELED = 'N'`.
+- Datumsfilter auf `DocDate >= ExportSettings.DateFilter`.
+
+Wichtige Feldbelegung:
+
+| Zielfeld | HANA/B1-Feld |
+| --- | --- |
+| `PostingDate` | `OINV.DocDate` / `ORIN.DocDate` |
+| `InvoiceDate` | `OINV.TaxDate` / `ORIN.TaxDate` |
+| `Material` | `INV1.ItemCode` / `RIN1.ItemCode` |
+| `Name` | `INV1.Dscription` / `RIN1.Dscription` |
+| `ProductGroup` | `OITB.ItmsGrpNam` |
+| `Quantity` | Invoice positiv, Credit Note negativ |
+| `SalesPriceValue` | `LineTotal`, bei Credit Note negativ |
+| `SalesCurrency` | `OADM.MainCurncy` |
+| `DocumentCurrency` | `DocCur` |
+| `DocumentTotalForeignCurrency` | `DocTotalFC`, bei Credit Note negativ |
+| `DocumentTotalLocalCurrency` | `DocTotal`, bei Credit Note negativ |
+| `VatSumForeignCurrency` | `VatSumFC`, bei Credit Note negativ |
+| `VatSumLocalCurrency` | `VatSum`, bei Credit Note negativ |
+| `DocumentRate` | `DocRate` |
+| `CompanyCurrency` | `OADM.MainCurncy` |
+| `DocumentType` | `INV` oder `CRN` |
+
+Italien hat zusaetzlich einen HANA-Filter:
+
+- `AcctCode LIKE '47005%'`
+- `AcctCode NOT LIKE '4700504%'`
+- bestimmte `CardCode`-Ausschluesse.
+
+Diese HANA-Filter greifen bereits beim Datenholen, also vor Transformation, Excel und `CentralSalesRecords`.
+
+### SAP OData / ZSCHWEIZ
+
+Betroffen:
+
+| Land | TSC | Quelle |
+| --- | --- | --- |
+| CH / AT | `ZSCHWEIZ` | SAP OData `ZPOWERBI_EINKAUF_SRV` |
+
+Aktive OData-Quellen:
+
+| Alias | EntitySet | Zweck |
+| --- | --- | --- |
+| `Z` | `FinanzdataSchweizOeSet` | Verkaufs-/Finance-Zeilen CH/AT |
+| `P` | `ProductDivisionRefSet` | zentrale TR-AG-Spartenreferenz |
+
+Join:
+
+```text
+Z.Matnr = P.Matnr
+```
+
+Wichtige Feldbelegung:
+
+| Zielfeld | Quelle |
+| --- | --- |
+| `Tsc` | `Z.Tsc` |
+| `Land` | `Z.Land1` |
+| `InvoiceNumber` | `Z.Vbeln` |
+| `PositionOnInvoice` | `Z.Posnr` |
+| `PostingDate` | `Z.Fkdat` |
+| `InvoiceDate` | `Z.Fkdat` |
+| `Material` | `Z.Matnr` |
+| `Name` | `Z.Arktx` |
+| `ProductGroup` | `Z.Prodh` |
+| `SalesPriceValue` | `Z.NetwrHc` |
+| `SalesCurrency` | `Z.Hwaer` |
+| `DocumentCurrency` | `Z.Waerk` |
+| `DocumentTotalForeignCurrency` | `Z.NetwrDc` |
+| `DocumentTotalLocalCurrency` | `Z.NetwrHc` |
+| `VatSumForeignCurrency` | `0` |
+| `VatSumLocalCurrency` | `0` |
+| `DocumentRate` | `Z.Kurrf` |
+| `CompanyCurrency` | `Z.Hwaer` |
+| `DocumentType` | `Z.Fkart` |
+
+Spartenfelder aus `P = ProductDivisionRefSet`:
+
+| Zielfeld | Quelle |
+| --- | --- |
+| `ProductHierarchyCode` | `P.Paph1` |
+| `ProductHierarchyText` | `P.Paph1Text` |
+| `ProductFamilyCode` | `P.Wwpfa` |
+| `ProductFamilyText` | `P.WwpfaText` |
+| `ProductDivisionCode` | `P.Wwpsp` |
+| `ProductDivisionText` | `P.WwpspText` |
+| `ProductMappingAssigned` | `P.IsAssigned` |
+
+Diese Spartenfelder werden beim ZSCHWEIZ-Export direkt in `CentralSalesRecords` gespeichert.
+
+### Manuelle Excel/CSV / SharePoint-Dateien
+
+Betroffen:
+
+| Land | Beispiel | Quelle |
+| --- | --- | --- |
+| UK | `TRUK` | SharePoint-Ordner `Import/Finance/UK_B1`, fachlich Sage |
+| Spanien | `TRES` / lokal auch `TRSE` in alten Daten | Sage CSV / SharePoint `Import/Finance/Spanien` |
+| Deutschland | `TRDE` | Alphaplan Excel |
+
+Ablauf:
+
+- Datei wird lokal, per UNC oder aus SharePoint geladen.
+- Bei SharePoint-Ordnern wird die passende neueste Datei bzw. bei Spanien alle `Spain_Sales*.csv` gelesen.
+- Spalten werden ueber manuelle Mappings oder Headernamen auf `SalesRecord` gemappt.
+- UK nutzt `SageNetSales([Sales Price/Value], [Quantity], [Document Type], ...)`.
+- Spanien-Deltas werden nach `SourceLineId`, sonst `TSC + InvoiceNumber + PositionOnInvoice + Material`, dedupliziert.
+
+Manuelle Dateien koennen Spartenfelder enthalten, wenn sie passende Spalten liefern. Im aktuellen fachlichen Zielbild sind lokale ERP-Sparten aber nicht fuehrend; die Spartenanalyse matched gegen TR-AG/SAP-Referenz.
+
+## Wann werden Felder veraendert?
+
+### Beim Datenholen / Mapping
+
+Die meisten Felder werden beim Import initial gesetzt:
+
+- HANA/B1: SQL-Abfrage erzeugt `SalesRecord` direkt.
+- SAP OData: OData-Zeilen werden per Mapping/Join in `SalesRecord` geschrieben.
+- Manual Excel/CSV: Excel-/CSV-Spalten werden per Mapping in `SalesRecord` geschrieben.
+
+Beispiele fuer aktive Veraenderung beim Holen:
+
+- B1-Gutschriften werden bereits negativ geladen:
+  - `Quantity * -1`
+  - `LineTotal * -1`
+  - `DocTotal * -1`
+  - `VatSum * -1`
+- ZSCHWEIZ setzt `VatSum* = 0`, weil Nettowerte aus `NetwrHc`/`NetwrDc` kommen.
+- ZSCHWEIZ haengt Spartenfelder aus `ProductDivisionRefSet` per Join an.
+- UK berechnet den Positionswert aus Stueckpreis mal Menge.
+- Spanien setzt Credit Notes / REC negativ.
+
+### Nach dem Datenholen: Transformationen
+
+Danach laufen aktive `FieldTransformationRules`:
+
+- Einfache Feldtransformationen kopieren/normalisieren Werte von `SourceField` nach `TargetField`.
+- `FirstNonEmpty` setzt ein Zielfeld aus dem ersten nicht-leeren Kandidatenfeld.
+- `ConvertCurrency` kann einen Betrag ueber die Kurstabelle in eine Zielwaehrung umrechnen und optional ein Ziel-Waehrungsfeld setzen.
+
+Wichtig: Transformationen laufen vor lokaler Standort-Excel und vor `CentralSalesRecords`. Falls eine aktive Transformation ein Feld veraendert, wird der veraenderte Wert in Excel und Datenbank gespeichert.
+
+### Beim Schreiben in CentralSalesRecords
+
+Es wird fachlich nichts neu berechnet. Die App speichert die nach Import und Transformation vorliegenden `SalesRecord`-Werte.
+
+Pro Standort:
+
+```text
+DELETE CentralSalesRecords WHERE SiteId = <Standort>
+INSERT neue Records fuer diesen Standort
+```
+
+## Wann wirkt der Wechselkurs?
+
+Es gibt drei getrennte Faelle.
+
+### 1. Standard-Finance-Soll/Ist und Finance Summary
+
+Kein allgemeiner Wechselkurs wird angewendet.
+
+- Fuehrend ist die Hauswaehrung / lokale Finance-Waehrung.
+- `Finance Summary` nutzt `SalesPriceValue` nach Finance-Regeln.
+- Anzeige bleibt nach vorhandener Waehrung gruppiert.
+- Wenn mehrere Waehrungen im Scope sind, zeigt die UI `Mixed`.
+
+Das gilt fuer:
+
+- Management Analyse > Finance Summary.
+- Management Analyse > Spartenanalyse.
+- Zentrale Excel-Blatt `Finance Summary`.
+- Zentrale Excel-Blatt `Finance Details`.
+
+### 2. Management Analyse / Rohdaten-Diagnose mit Zielwaehrung
+
+Wenn in Analyse-Sichten eine Zielwaehrung wie `CHF`, `EUR` oder `USD` ausgewaehlt wird, rechnet die UI-Anzeige zur Laufzeit um.
+
+Quelle:
+
+- `CurrencyExchangeRates`
+- gewaehltes `ExchangeRateDateField` aus Settings:
+  - `PostingDate`
+  - `InvoiceDate`
+  - `ExtractionDate`
+
+Die Umrechnung passiert beim Anzeigen/Aggregieren in `ManagementCockpitService`, nicht beim Standortexport und nicht beim Erzeugen der zentralen Excel.
+
+Wenn kein Kurs gefunden wird:
+
+- Anzeige-Wert wird fuer diese Zeile `0` in der Zielwaehrung.
+- `MissingExchangeRate` wird gezaehlt und in Diagnosehinweisen angezeigt.
+
+### 3. Explizite Transformation `ConvertCurrency`
+
+Falls eine aktive `FieldTransformationRule` vom Typ `ConvertCurrency` gepflegt ist, passiert die Umrechnung beim Standortexport vor `CentralSalesRecords`.
+
+Dann wird das konfigurierte Zielfeld dauerhaft mit dem umgerechneten Betrag beschrieben.
+
+Standardlogik fuer Datum bei `ConvertCurrency`:
+
+- konfiguriertes `dateField`, falls angegeben.
+- sonst `InvoiceDate`.
+- sonst `OrderDate`.
+- sonst `ExtractionDate`.
+
+## Finance-Regeln und Finance-Wert
+
+Die Finance-Sicht wird nicht durch Excel-Formeln bestimmt, sondern durch `FinanceRuleEngine`.
+
+Zeitliche Abgrenzung:
+
+```text
+FinanceDate = PostingDate
+sonst InvoiceDate
+sonst ExtractionDate
+```
+
+Ausnahme:
+
+- DE kann per Finance-Regel auf Jahr 2025 gezwungen werden, weil Alphaplan als Jahresfile geliefert wird.
+
+Include/Exclude:
+
+- Regeln koennen Zeilen ausschliessen.
+- Regeln koennen Werte negativ setzen.
+- Regeln koennen IT-Duplikate mit leerem Supplier Country deduplizieren.
+
+Aktuelle Default-/Fachregeln:
+
+- DE:
+  - Jahresfile 2025.
+  - `Trafag AG` ausschliessen.
+  - `Magnetic Sense` ausschliessen.
+  - `GS2510095` ausschliessen.
+  - Gutschriften mit `GS...` negativ.
+- IT:
+  - `CustomerName` enthaelt `Trafag Italia` ausschliessen.
+  - IT-Zeilen mit leerem Supplier Country deduplizieren.
+
+Der Finance-Wert ist:
+
+```text
+Net Sales Actual = SalesPriceValue nach FinanceRuleEngine
+```
+
+## Zentrale Excel
+
+Ausloeser:
+
+- Export Dashboard > `Zentrale Datei neu erzeugen`.
+- Nach `Alle exportieren` automatisch am Ende.
+
+Ablauf:
+
+1. `ConsolidatedExportService` liest alle Saetze aus `CentralSalesRecords`.
+2. `ExcelExportService.CreateConsolidatedExcelFile(...)` erzeugt `Sales_All_<Datum>.xlsx`.
+3. Die Datei wird lokal geschrieben.
+4. Falls SharePoint konfiguriert ist, wird sie hochgeladen.
+
+Ziel lokal:
+
+- `ExportSettings.LocalConsolidatedExportFolder`, falls gesetzt.
+- sonst `ExportSettings.LocalSiteExportFolder`, falls gesetzt.
+- sonst `<App-Verzeichnis>/output`.
+
+Ziel SharePoint:
+
+- Wenn `CentralExportFolder` gesetzt ist: direkt dorthin.
+- Sonst: `ExportFolder/Alle`.
+
+Die zentrale Excel enthaelt:
+
+- Blatt `Finance Summary`.
+- Blatt `Finance Details`.
+- Blatt `Sales`.
+- optional Hilfeblatt.
+
+Wichtig:
+
+- `Finance Summary` im Excel wird beim Schreiben aus den Records berechnet.
+- Es liest nicht aus einem vorherigen SharePoint-Excel.
+- Wechselkurs-Zielwaehrung aus der UI wird dabei nicht angewendet.
+
+## Finance Summary und Spartenanalyse in der App
+
+Die App-Anzeigen lesen direkt aus:
+
+```text
+CentralSalesRecords
+```
+
+Nicht aus:
+
+```text
+SharePoint Sales_All_*.xlsx
+```
+
+Das bedeutet:
+
+- Lokal zeigt die App lokale DB-Daten.
+- Publizierter Server zeigt Server-DB-Daten.
+- Wenn lokale und Server-DB gleich sind, sehen beide gleich aus.
+- Ein SharePoint-Upload veraendert die App-Anzeige nicht.
+
+## Spartenanalyse: genaue Logik
+
+### Quelle der Spartenreferenz
+
+Fuehrend ist `ProductDivisionRefSet` aus SAP/TR-AG.
+
+Technisch landet diese Referenz aktuell ueber den ZSCHWEIZ-Export in `CentralSalesRecords`, weil ZSCHWEIZ die Quelle `P = ProductDivisionRefSet` per `Z.Matnr = P.Matnr` joint.
+
+Die Analyse baut daraus eine Referenz:
+
+```text
+Materialnummer -> PAPH1 / Produktfamilie / Produktsparte / IsAssigned
+```
+
+Materialnummern werden normalisiert:
+
+- Trim.
+- Grossschreibung.
+- Leerzeichen entfernen.
+- fuehrende Nullen entfernen.
+
+### Status in der Spartenanalyse
+
+| Status | Bedeutung |
+| --- | --- |
+| `Zugeordnet` | Material in TR-AG-Referenz gefunden und `ProductMappingAssigned` ist wahr, Produktsparte ist nicht leer und nicht `UNASS`. |
+| `Nicht zugeordnet` | Material in TR-AG-Referenz gefunden, aber Spartenwert leer/`UNASS`/nicht assigned. |
+| `Nicht im TR-AG-Stamm` | Materialnummer aus lokalem Finance-Umsatz hat keinen Treffer in der TR-AG-Referenz. |
+| `Material fehlt` | Finance-Zeile hat keine Materialnummer. |
+
+### Warum aktuell viele `Nicht im Stamm` entstehen koennen
+
+Die aktuellen Daten zeigen Produktfelder nur bei CH/AT direkt gefuellt. Andere Laender werden ueber Materialnummern gegen die TR-AG-Referenz gematcht.
+
+Wenn lokale Artikelnummern nicht identisch mit TR-AG-Materialnummern sind, entstehen `Nicht im TR-AG-Stamm`.
+
+Typische Ursachen:
+
+- lokale Materialnummern statt TR-AG-MATNR.
+- Sage-/B1-Artikelnummern, die nicht im TR-AG-Stamm existieren.
+- Indien-Artikel wie `DM000010`, `DM000001`, `PT000003`, `IC15415`, die lokal hohe Werte tragen, aber keinen Treffer in der TR-AG-Referenz haben.
+- fehlende oder unvollstaendige `ProductDivisionRefSet`-Fuellung.
+- Materialnummernformat trotz Normalisierung nicht kompatibel.
+
+## Datenflussdiagramm Textform
+
+```text
+Standort Export starten
+  |
+  +-- HANA/B1: OINV/INV1 + ORIN/RIN1 lesen
+  |       -> Gutschriften bereits negativ
+  |       -> IT-HANA-Filter bereits in SQL
+  |
+  +-- SAP OData ZSCHWEIZ:
+  |       -> FinanzdataSchweizOeSet lesen
+  |       -> ProductDivisionRefSet lesen
+  |       -> Join Z.Matnr = P.Matnr
+  |       -> Spartenfelder in SalesRecord
+  |
+  +-- Manual Excel/CSV/SharePoint:
+          -> Datei(en) laden
+          -> Mapping/SageNetSales/Spain-Dedupe
+
+SalesRecord-Liste
+  |
+  +-- FieldTransformationRules anwenden
+  |       -> optional Feldkopien, FirstNonEmpty, ConvertCurrency
+  |
+  +-- Standort-Excel Sales_<TSC>_<Datum>.xlsx lokal schreiben
+  |
+  +-- CentralSalesRecords fuer SiteId ersetzen
+  |
+  +-- Standort-Excel optional nach SharePoint hochladen
+
+Finance Summary / Spartenanalyse
+  |
+  +-- liest CentralSalesRecords
+  +-- FinanceRuleEngine rechnet Include/Exclude/Net Sales Actual
+  +-- Spartenanalyse matched lokale Materialien gegen TR-AG-Referenz aus CentralSalesRecords
+
+Zentrale Excel
+  |
+  +-- liest CentralSalesRecords
+  +-- erzeugt Sales_All_<Datum>.xlsx lokal
+  +-- erzeugt Finance Summary / Finance Details im Excel
+  +-- laedt Datei optional nach SharePoint
+```
+
+## Wichtige Klarstellungen fuer Finance
+
+1. SharePoint ist Ablage und Quelle fuer manuelle Dateien, aber nicht Live-Quelle der Finance Summary.
+2. `CentralSalesRecords` ist der operative zentrale Datenbestand der App.
+3. Sparten kommen fachlich aus TR-AG/SAP `ProductDivisionRefSet`, nicht aus lokalen ERP-Sparten.
+4. CH/AT bekommen Spartenfelder direkt beim ZSCHWEIZ-Export.
+5. Andere Laender bekommen Sparten in der Analyse nur, wenn ihre Materialnummern zur TR-AG-Referenz matchen.
+6. Wechselkurse sind keine stille Vorverarbeitung fuer den Standard-Soll/Ist-Abgleich.
+7. `Mixed` bedeutet: mehrere Waehrungen im Filter. Prozentwerte auf `Mixed` sind nur eingeschraenkt interpretierbar; fuer belastbare Spartenanteile nach Wert muss Land oder Waehrung gefiltert werden.
+8. Die zentrale Excel wird nach den Standortexporten aus `CentralSalesRecords` erstellt. Sie ist Ergebnis, nicht Eingang.
+