admin/Ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e20693243d4887c1a86e281b99a406a477d61c01
Ai/TrafagSalesExporter/LLM_SYSTEM_GUIDE.md
T

25 KiB
Raw Blame History

TrafagSalesExporter LLM System Guide

Stand: 2026-05-05

Aktueller Projektstand 2026-05-05

Fuer den aktuellen Finance-/Laenderabgleich zuerst diese Dateien lesen:

Lokaler FinanceProbe:

http://localhost:55417/finance

Aktueller Zusatzstand 2026-05-07 SAP OData / ZSCHWEIZ

Schweiz/Oesterreich werden ueber eine neue SAP-Tabelle ZSCHWEIZ bereitgestellt.

Wichtige Punkte:

  • ABAP-Report: report.abap
  • SAP-Tabelle: ZSCHWEIZ
  • OData EntitySet: ZSCHWEIZSet
  • App-Standort: ZSCHWEIZ / Schweiz/Oesterreich
  • Geplanter App-Pfad: SAP = SAP OData, nicht direkter HANA-Spezialcode

Quellsystem-Codes:

  • SAP: SAP OData/Gateway, DisplayName SAP OData
  • SAP_HANA: direkte HANA-Tabellen/Views, DisplayName SAP HANA Tables/Views
  • BI1: HANA
  • SAGE: HANA
  • MANUAL_EXCEL: Excel/CSV

Mapper:

  • SAP OData nutzt SapSourceDefinition, SapJoinDefinition, SapFieldMapping.
  • Direkte HANA-Tabellen/Views koennen dieselben Mapping-Tabellen ebenfalls nutzen.
  • Gemeinsame Mapping-Engine ist MappedSalesRecordComposer.
  • SapCompositionService und HanaQueryService.GetMappedSalesRecordsAsync unterscheiden sich nur noch in der Quellenbeschaffung; Join und SalesRecord-Mapping sind zentral.
  • Bei HANA mit gepflegten Quellen/Mappings nutzt HanaDataSourceAdapter den generischen Mapping-Pfad.
  • Ohne HANA-Mapping bleibt der alte B1-HANA-Standardpfad fuer OINV/INV1/ORIN/RIN1 aktiv.

Finance-Konfiguration:

  • FinanceReferences enthaelt Soll-/check.xlsx-Referenzen.
  • FinanceIntercompanyRules enthaelt 2nd-party/IC-Regeln.
  • Budgetkurse werden als CurrencyExchangeRates mit Notes = Budget 2025 gepflegt.
  • Config-Export/-Import umfasst Finance-Referenzen und IC-Regeln.

ZSCHWEIZ-Seed:

  • Quelle Alias Z
  • EntitySet ZSCHWEIZSet
  • Mapping auf SalesRecord ist vorbefuellt und grafisch editierbar.
  • Beim App-Start wird die ZSCHWEIZ-Quelle samt Feldmapping per Upsert angelegt oder repariert.
  • Wenn Gateway $metadata liefert, koennen Felder in der UI per Felder aus Quellen laden gelesen werden.

ABAP-Fachlogik:

  • BUKRS 1100 = Schweiz, TSC TRCH, LAND1 CH
  • BUKRS 1200 = Oesterreich, TSC TRAT, LAND1 AT
  • CUSTOMER_LAND = Kundenland aus KNA1-LAND1
  • Netto-/Steuerwerte werden in Belegwaehrung und Hauswaehrung geschrieben.

Aktuelle FinanceProbe-Funktionen:

  • Meeting Ampel 2025 fuer alle Laender aus check.xlsx
  • Detail alle Laender
  • Spain CSV direct check
  • Germany Excel sample check

Spanien:

  • Datei: sagespain/v2/Spain_Sales_2025.csv
  • Ist: 3'082'320.18 EUR
  • Soll: 3'102'333.61
  • Differenz: -20'013.43
  • Status: Gelb / Pruefen
  • Technisch lesbar, fachliche Differenz noch offen

Deutschland:

  • Datei: DE_Beispiel_Export_Daten.xlsx
  • Sample-Summe NettoPreisGesamtX: 8'290.70 EUR
  • Nur Beispielfile, keine finale Jahreszahl
  • Mapping technisch verstanden, finaler DE-Jahresfile fehlt

Letzte Verifikation:

  • dotnet build .\Tools\FinanceProbe\FinanceProbe.csproj --verbosity minimal --no-restore
  • dotnet test .\TrafagSalesExporter.Tests\TrafagSalesExporter.Tests.csproj --verbosity minimal --no-restore
  • Ergebnis: Build OK, Tests 50/50, FinanceProbe HTTP 200

Diese Datei ist fuer andere LLMs gedacht, die das Projekt schnell verstehen und daraus Architekturtexte, Visualisierungen, Ablaufdiagramme oder UI-/Datenflussgrafiken erzeugen sollen.

Zweck des Systems

TrafagSalesExporter ist eine Blazor Server App auf .NET 8, die Verkaufsdaten aus mehreren Quellsystemen in ein gemeinsames Zielschema ueberfuehrt.

Quellsysteme:

  • HANA-basierte Systeme wie BI1 und SAGE
  • SAP_GATEWAY ueber OData
  • MANUAL_EXCEL aus hochgeladenen oder referenzierten Excel-Dateien

Zielbild:

  • jede Quelle wird in SalesRecord normalisiert
  • Standortdaten koennen lokal als Excel exportiert werden
  • alle Datensaetze werden in CentralSalesRecords gespeichert
  • eine zentrale konsolidierte Datei wird aus dem zentralen Datenbestand erzeugt
  • ein Management Cockpit analysiert sowohl exportierte Dateien als auch zentrale Rohdaten

Technologie-Stack

  • UI: Blazor Server + MudBlazor
  • Authentifizierung: ASP.NET Core Authentication/Authorization, produktiv Windows Authentication / Active Directory
  • Datenbank: SQLite (trafag_exporter.db)
  • Excel lesen/schreiben: ClosedXML
  • SAP HANA Zugriff: Sap.Data.Hana.Core.v2.1.dll
  • SAP Gateway / OData: eigener Service ueber HTTP
  • SharePoint Upload/Download: Microsoft Graph + Azure Identity
  • Tests: xUnit

Einstiegspunkte

Wichtige Dateien:

Program.cs registriert fast die komplette Architektur ueber DI und fuehrt beim Start DatabaseInitializationService.InitializeAsync() aus.

Zusaetzlich registriert Program.cs den Zugriffsschutz:

  • AddCascadingAuthenticationState
  • Windows Authentication fuer produktive Umgebungen
  • Development-Authentication-Handler nur bei ASPNETCORE_ENVIRONMENT=Development und Security:DevelopmentBypass=true
  • globale Fallback-Policy fuer authentifizierte/berechtigte User
  • Policy AdminOnly fuer administrative Seiten

Hauptseiten

Navigation:

  • / Dashboard
  • /standorte
  • /transformations
  • /management-cockpit
  • /settings
  • /logs

Dateien:

Kurzrollen:

  • Dashboard: Einzel-Export, Alle exportieren, zentrale Datei neu erzeugen, Live-Status
  • Standorte: Standortpflege, zentrale HANA-Technik, SAP-Konfiguration pro Standort, manueller Excel-Import
  • Transformations: feldweise und record-basierte Regeln
  • Management Cockpit: Dateianalyse und Rohanalyse aus CentralSalesRecords
  • Settings: SharePoint, Exportpfade, Quellsysteme, Wechselkurse, Config Import/Export
  • Logs: technische Ereignisprotokolle

Security:

  • alle Routen erfordern Authentifizierung
  • Settings, Standorte und Transformations sind AdminOnly
  • Admin-Navigation wird nur fuer Admins angezeigt
  • eingeloggter Benutzer wird im App-Bar angezeigt

Kernmodelle

Wichtige Entity-Klassen:

SalesRecord / CentralSalesRecord enthalten neben den positionsnahen Feldern auch B1-Belegwaehrungsfelder:

  • DocumentCurrency aus DocCur
  • DocumentTotalForeignCurrency aus DocTotalFC
  • DocumentTotalLocalCurrency aus DocTotal
  • VatSumForeignCurrency aus VatSumFC
  • VatSumLocalCurrency aus VatSum
  • DocumentRate aus DocRate
  • CompanyCurrency aus OADM.MainCurncy

Wichtig: diese Dokumentwerte sind Belegkopfwerte und werden in der positionsbasierten Excel pro Position wiederholt. Fuer Belegkopfsummen muessen Auswertungen nach Beleg deduplizieren.

Wichtige Relationen:

  • Site -> HanaServer optional
  • Site -> SapSourceDefinitions
  • Site -> SapJoinDefinitions
  • Site -> SapFieldMappings
  • Site -> CentralSalesRecords
  • SourceSystemDefinition ist zentrale Stammdatenquelle fuer Quellsysteme

Datenbanktabellen

AppDbContext enthaelt:

  • HanaServers
  • SourceSystemDefinitions
  • Sites
  • SharePointConfigs
  • ExportSettings
  • ExportLogs
  • AppEventLogs
  • FieldTransformationRules
  • CurrencyExchangeRates
  • SapSourceDefinitions
  • SapJoinDefinitions
  • SapFieldMappings
  • CentralSalesRecords

Architekturrollen der Services

Export / Orchestrierung

Rollen:

  • ExportOrchestrationService steuert UI-nahe Exportlaeufe und Live-Status
  • SiteExportService entscheidet anhand des Quellsystems, wie ein Standort gelesen wird
  • CentralSalesRecordService ersetzt zentrale Saetze pro Standort
  • ConsolidatedExportService erzeugt die zentrale Datei

Datenquellen

Rollen:

  • HanaQueryService: SQL gegen SAP B1/HANA-nahe Schemata
  • SapGatewayService: OData-Metadaten und Reads
  • SapCompositionService: Mehrquellen-/Join-/Mapping-Aufbau fuer SAP
  • ManualExcelImportService: Import im Exportformat aus .xlsx
  • SharePointUploadService: Upload fuer Exportdateien und Download fuer manuelle Excel-Dateien

Transformation / Mapping

Rollen:

  • Value-Transformationen fuer einzelne Felder
  • Record-Transformationen fuer zeilenweite Regeln
  • Wechselkursimport und -umrechnung

Reporting / Monitoring / Infrastruktur

Der wichtigste technische Ablauf

1. Standort-Export

Pfad:

Dashboard/Standorte -> ExportOrchestrationService -> SiteExportService

SiteExportService unterscheidet drei Modi:

  1. SAP_GATEWAY

    • SAP-Quellen lesen
    • SAP-Joins anwenden
    • SAP-Feldmappings auf SalesRecord
    • Transformationen anwenden
    • Standort-Excel erzeugen
    • CentralSalesRecords ersetzen
    • optional SharePoint-Upload

  2. HANA

    • effektive zentrale HANA-Konfiguration laden
    • optionale Standort-Credential-Overrides anwenden
    • SQL in HANA ausfuehren
    • SalesRecord erzeugen
    • Transformationen anwenden
    • Standort-Excel erzeugen
    • CentralSalesRecords ersetzen
    • optional SharePoint-Upload

  3. MANUAL_EXCEL

    • ManualImportFilePath auswerten
    • wenn lokal/UNC vorhanden: lokal lesen
    • wenn SharePoint-Referenz: via Graph temp herunterladen
    • Excel in SalesRecord lesen
    • Transformationen anwenden
    • keine neue Standortdatei erzeugen, bestehende Excel dient als Eingabe
    • CentralSalesRecords ersetzen

2. Konsolidierter Export

Pfad:

Dashboard -> ExportOrchestrationService -> ConsolidatedExportService

Semantik aktuell:

  • die zentrale Datei basiert fachlich auf CentralSalesRecords
  • ExportAllAsync() sammelt zwar auch consolidatedRecords, aber die zentrale Exportsemantik ist historisch noch nicht vollkommen bereinigt

3. Management Cockpit

Zwei Betriebsarten:

  1. Dateibasiert

    • vorhandene .xlsx waehlen
    • Datei mit ClosedXML lesen
    • Summenfeld waehlen
    • Anzeige-Waehrung waehlen
    • Kennzahlen, Top-Listen, Datenqualitaet, Findings erzeugen

  2. Zentraldatenbasiert

    • direkt aus CentralSalesRecords
    • Jahr/Monat Filter
    • Summenfeld waehlen
    • optionale weitere Summenfelder fuer Zeitreihen waehlen
    • Anzeige-Waehrung waehlen
    • Rohsicht ohne Intercompany-, Budget- oder Spartelogik

Aktuelle Summenfelder:

  • Sales Price/Value
  • Quantity
  • Standard cost
  • Quantity * Standard cost

Aktuelle Anzeige-Waehrungen:

  • EUR
  • USD
  • Original

Die Waehrungsumrechnung nutzt CurrencyExchangeRateService. Bei Original bleiben Werte in Quellwaehrungen gruppiert. Nicht-betragliche Summenfelder wie Quantity haben keine Waehrung. Fehlende Wechselkurse werden gezaehlt und in Hinweisen bzw. Findings sichtbar; betroffene Werte werden in der Zielwaehrung mit 0 einbezogen.

Quellsystemlogik

SourceSystemDefinition

SourceSystemDefinition ist die fuehrende Wahrheit fuer:

  • Code
  • DisplayName
  • ConnectionKind
  • IsActive
  • CentralUsername
  • CentralPassword
  • CentralServiceUrl fuer SAP

Anschlussarten:

  • HANA
  • SAP_GATEWAY
  • MANUAL_EXCEL

HANA

Fachliche Logik:

  • zentrale technische HANA-Konfiguration pro Quellsystem
  • keine separaten Vollverbindungen pro Standort
  • Standort speichert nur Fachdaten plus optionale Username-/Password-Overrides

Schema-Lookup:

  • in Standorte gibt es jetzt Schemas laden
  • Lookup fragt sys.tables in HANA ab
  • eingeschraenkt auf typische B1-Schemas mit Tabellen wie OINV, INV1, ORIN, RIN1, OCRD, OITM

SAP

Fachliche Logik:

  • zentrale SAP Service URL in SourceSystemDefinition.CentralServiceUrl
  • Standort kann SapServiceUrl als Override pflegen
  • pro Standort gibt es SAP-Quellen, Joins und Feldmappings

Manual Excel

Fachliche Logik:

  • Site.ManualImportFilePath kann sein:
    • lokaler Windows-Pfad
    • UNC-Pfad
    • SharePoint-URL
    • SharePoint-Pfad unterhalb der konfigurierten Site
  • Standortdaten werden aus der Excel eingelesen und in CentralSalesRecords uebernommen
  • SharePoint dient hier als Eingangsquelle, nicht nur als Exportziel

Transformationen

Das System unterscheidet:

  • Value-Transformationen
  • Record-Transformationen

Beispiele:

  • Copy
  • Uppercase
  • Lowercase
  • Prefix
  • Suffix
  • Replace
  • Constant
  • NormalizeCurrencyCode
  • FirstNonEmpty
  • ConvertCurrency

Technischer Ablauf:

  • Regeln liegen in FieldTransformationRules
  • TransformationCatalog meldet verfuegbare Strategien an die UI
  • RecordTransformationService wendet record-basierte Strategien an

Wechselkurse

Vorhanden:

  • CurrencyExchangeRates
  • ExchangeRateImportService fuer ECB-Tageskurse
  • NormalizeCurrencyCode
  • ConvertCurrency
  • ManagementCockpitService kann betragliche Cockpit-Kennzahlen in EUR oder USD umrechnen

Wichtig:

  • die Rohsicht im Management Cockpit kann jetzt Anzeige-Waehrungen nutzen
  • CHF ist im Cockpit aktuell nicht als direkte Anzeige-Waehrung in der UI angeboten
  • CHF bleibt weiterhin Teil des allgemeinen Transformationssystems
  • fachlich ist noch zu klaeren, ob CHF als Standard- oder zusaetzliche Cockpit-Anzeige-Waehrung gebraucht wird

SharePoint-Rolle im Gesamtsystem

SharePointConfig enthaelt:

  • SiteUrl
  • ExportFolder
  • CentralExportFolder
  • TenantId
  • ClientId
  • ClientSecret

Verwendung:

  • Upload von Standort-Exporten
  • Upload der zentralen Datei
  • Download von manuellen Excel-Dateien fuer MANUAL_EXCEL

Wichtig:

  • die App arbeitet gegen dieselbe SharePoint-Site, die in Settings konfiguriert ist
  • fuer MANUAL_EXCEL muessen Referenzen auf derselben Site aufloesbar sein

Startinitialisierung / Migrationen

Kritische Datei:

Aktuelle Rolle:

  • EnsureCreated
  • Schema-Ergaenzungen per ALTER TABLE
  • Tabellen-Rebuilds bei Legacy-Schemas
  • FK-Reparaturen
  • Stammdaten-Seeding
  • empfohlene Transformationsregeln

Bekannte Architekturrealitaet:

  • das ist funktional hilfreich, aber kein sauberes Migrationssystem
  • die Startlogik traegt produktive Schema-Reparaturverantwortung
  • das ist einer der wichtigsten technischen Risikobloecke

Bereits gehaertete Fehlerbilder:

  • kaputte FK-Referenzen auf Sites_old
  • kaputte FK-Referenzen auf HanaServers_repair_old
  • Legacy-Credential-Spalten in ExportSettings
  • Legacy-Credential-Spalten in HanaServers
  • verschobene Spalten im Sites_old -> Sites-Kopierpfad

Authentifizierung / Autorisierung

Dateien:

Produktives Ziel:

  • Windows Authentication / Active Directory
  • keine eigene Benutzerverwaltung
  • Zugriff ueber AD-Gruppen
  • Adminrechte ueber separate AD-Gruppe

Konfiguration in appsettings.json:

  • Security:AccessGroups
  • Security:AdminGroups
  • Security:DevelopmentBypass
  • Security:DevelopmentUserIsAdmin
  • Security:DevelopmentUserName

Default-Gruppen:

  • TRAFAG\\TrafagSalesExporter-Users
  • TRAFAG\\TrafagSalesExporter-Admins

Development:

  • appsettings.Development.json aktiviert einen lokalen Development-Auth-Handler
  • dieser ist nur fuer lokale Entwicklung gedacht
  • produktiv darf ASPNETCORE_ENVIRONMENT nicht Development sein

IIS-Betrieb:

  • Windows Authentication aktivieren
  • Anonymous Authentication deaktivieren
  • AD-Gruppennamen in produktiver Konfiguration setzen

Config Import / Export

Dateien:

Aktueller Stand:

  • JSON Export/Import fuer Konfiguration
  • Secrets optional
  • SourceSystemDefinitions im aktuellen Modell enthalten
  • HANA-Technik ohne HANA-Credentials
  • Standort-Overrides bleiben erhalten

Wichtige Punkte:

  • Import laeuft jetzt transaktional
  • alte ConnectionKind-lose Formate bekommen Fallbacks
  • CentralSalesRecords werden nicht mehr blind geloescht
  • bestehende zentrale Laufzeitdaten werden fuer weiterhin vorhandene Standorte remappt

Logging

Es gibt zwei Log-Ebenen:

  • ExportLogs fuer fachliche Exporthistorie
  • AppEventLogs fuer technische und UI-nahe Ereignisse

Die Logs-Seite liest vor allem AppEventLogs.

Tests

Testprojekt:

Aktuell vorhandene Schwerpunkte:

  • Transformationen
  • Record-Transformationen
  • TransformationCatalog
  • CurrencyExchangeRateService
  • ExchangeRateImportService
  • ManualExcelImportService
  • ManagementCockpitService
  • ConfigTransferService
  • DatabaseInitializationService

ManagementCockpitServiceTests decken inzwischen auch ab:

  • zentrale Analyse nach Jahr/Monat
  • Tages-, Monats-, Jahres-, Quellen- und Laenderwerte
  • waehlbare Summenfelder
  • Waehrungsumrechnung in EUR
  • Wechselkurs-Caching
  • Mengen-Auswertung ohne Waehrungsumrechnung
  • Zusatz-Summenfelder in Zeitreihen

SecurityPolicyFactoryTests decken inzwischen ab:

  • App-Zugriff fuer User in AccessGroups
  • Ablehnung fuer User ausserhalb der Access-Gruppen
  • Development-Auth-Zugriff im lokalen Modus
  • Admin-Zugriff fuer User in AdminGroups
  • Ablehnung normaler User fuer AdminOnly
  • Development-Admin-Claim

CentralSalesRecordServiceTests decken inzwischen ab:

  • Persistenz und Ruecklesen der B1-Belegwaehrungsfelder in CentralSalesRecords

Wichtig:

  • es gibt aktuell keine echten UI-Komponententests mit bUnit
  • es gibt keine Browser-E2E-Tests mit Playwright
  • viele Button-Aktionen sind nur indirekt ueber Services und Persistenz getestet

Bekannte offene Architekturfragen

Fuer andere LLMs wichtig, damit Visualisierungen nicht zu glatt oder zu idealisiert werden:

  1. DatabaseInitializationService ist ein produktiver Reparatur-/Migrationslayer, nicht nur Bootstrap.
  2. Settings.razor und Standorte.razor enthalten weiterhin relativ viel Anwendungslogik.
  3. Die Semantik der konsolidierten Datei ist historisch teilweise doppelt angelegt.
  4. Das Management Cockpit ist noch kein voll generalisierter Reporting-Layer.
  5. SharePoint ist sowohl Exportziel als auch bei MANUAL_EXCEL mittlerweile moegliche Eingangsquelle.

Empfohlene Diagramme fuer andere LLMs

1. Kontextdiagramm

Zeige:

  • Benutzer
  • Blazor App
  • SQLite
  • SAP HANA
  • SAP Gateway
  • lokale Dateisystempfade
  • SharePoint

2. Komponenten-/Service-Diagramm

Gruppiere:

  • UI
  • Orchestrierung
  • Quelladapter
  • Transformation
  • Persistenz
  • Reporting

3. Datenflussdiagramm pro Quelltyp

Je ein separater Flow fuer:

  • HANA
  • SAP Gateway
  • Manual Excel lokal
  • Manual Excel SharePoint

4. ER-Diagramm

Fokussiere auf:

  • SourceSystemDefinition
  • HanaServer
  • Site
  • SapSourceDefinition
  • SapJoinDefinition
  • SapFieldMapping
  • CentralSalesRecord
  • FieldTransformationRule

5. Sequenzdiagramm fuer Export

Wichtige Stationen:

  • Dashboard
  • ExportOrchestrationService
  • SiteExportService
  • spezifischer Quellservice
  • Transformation
  • CentralSalesRecordService
  • Excel/SharePoint
  • ExportLog/AppEventLog

Prompt-Vorlage fuer ein anderes LLM

Wenn ein anderes LLM daraus Visualisierungen erzeugen soll, funktioniert diese Anweisung gut:

Lies LLM_SYSTEM_GUIDE.md als primaeren Systemkontext. Erzeuge daraus ein Architekturdiagramm, ein Datenflussdiagramm fuer HANA/SAP/MANUAL_EXCEL, ein ER-Diagramm der wichtigsten Tabellen und ein Sequenzdiagramm fuer ExportAsync. Achte darauf, dass DatabaseInitializationService produktive Reparaturlogik enthaelt und dass MANUAL_EXCEL sowohl lokal als auch ueber SharePoint gelesen werden kann.

Weitere Kontextdateien

Zusatzkontext fuer Verlauf und Risiken:

Diese beiden Dateien sind wichtig, wenn ein anderes LLM nicht nur Struktur, sondern auch historische Umbauten, Risiken und Prioritaeten verstehen soll.

Reference in New Issue View Git Blame Copy Permalink