Update handoff docs for adapter and HANA refactor

2026-04-17 14:48:53 +02:00
parent ad2c6dbd53
commit 49c03b9673
2 changed files with 221 additions and 0 deletions
@@ -2,6 +2,133 @@
 Stand: 2026-04-15
 ## Nachtrag 2026-04-17 Refactoring- und HANA-Stand
 Der Stand aus den frueheren Nachtraegen ist fuer Architektur und HANA-Zugriff nicht mehr vollstaendig.
 Inzwischen gilt zusaetzlich:
 ### 1. DataSourceAdapter-Pattern ist eingefuehrt
 Die Quellsysteme `HANA`, `SAP_GATEWAY` und `MANUAL_EXCEL` laufen nicht mehr ueber einen grossen `if/else`-Block im `SiteExportService`.
 Neu:
 - `Services/DataSources/IDataSourceAdapter.cs`
 - `Services/DataSources/IDataSourceAdapterResolver.cs`
 - `Services/DataSources/DataSourceAdapterResolver.cs`
 - `Services/DataSources/DataSourceFetchContext.cs`
 - `Services/DataSources/DataSourceFetchResult.cs`
 - `Services/DataSources/DataSourceCredentials.cs`
 - `Services/DataSources/HanaDataSourceAdapter.cs`
 - `Services/DataSources/SapGatewayDataSourceAdapter.cs`
 - `Services/DataSources/ManualExcelDataSourceAdapter.cs`
 Neuer Zuschnitt:
 - `SiteExportService` ist jetzt deutlich schlanker und nur noch Export-Pipeline
 - Adapter loesen Quellsystem-spezifisches Laden auf
 - fuer ein weiteres Quellsystem ist kein Umbau im `SiteExportService` mehr noetig
 ### 2. Page-Services sind nicht mehr Singleton
 UI-nahe Services laufen jetzt pro Blazor-Circuit als `Scoped`.
 Betroffen:
 - `ISettingsPageService`
 - `IStandortePageService`
 - `IStandorteSapEditorService`
 - `IManagementCockpitPageService`
 - `IDashboardPageService`
 - `ILogsPageService`
 - `ITransformationsPageService`
 Wichtig:
 - `ExportOrchestrationService` bleibt bewusst `Singleton`, weil Exportstatus ueber Circuits geteilt werden muss
 - stateless Infrastruktur-Services bleiben weiter `Singleton`
 ### 3. Datenbank-Initialisierung ist aufgeteilt
 Der fruehere monolithische `DatabaseInitializationService` ist inzwischen in grobe Verantwortungsbloecke getrennt:
 - `DatabaseInitializationService` als Orchestrator
 - `DatabaseSchemaMaintenanceService` fuer Schema-/Repair-Logik
 - `DatabaseSeedService` fuer Defaultdaten und Stammdaten-Seeding
 - `DatabaseInitializationService.SchemaSql.cs` als SQL-Definitionsblock
 Das reduziert das groesste Architektur-Risiko deutlich, auch wenn die Startmigrationen weiterhin ein sensibler Teil des Systems bleiben.
 ### 4. Weitere Razor-Seiten sind entlastet
 Neben den frueher bereits entlasteten Seiten laufen jetzt auch diese Seiten ueber Page-Services statt direkten `DbContext`-Zugriffen:
 - `Dashboard.razor` ueber `DashboardPageService`
 - `Logs.razor` ueber `LogsPageService`
 - `Transformations.razor` ueber `TransformationsPageService`
 Der Rest an direkter Persistenzlogik in Razor ist damit deutlich kleiner geworden.
 ### 5. Kritische HANA-Risiken wurden entschärft
 #### SQL-Injection-Schutz
 Im `HanaQueryService` wurden die kritischen interpolierten SQL-Stellen bereinigt:
 - `tsc` und `dateFilter` laufen jetzt parametriert in `HanaCommand`
 - `schema` wird als Identifier streng validiert und gequotet
 Damit ist der akute Injection-Pfad in den HANA-Verkaufsabfragen geschlossen.
 #### Async statt `.GetAwaiter().GetResult()`
 Die blockierenden HANA-Aufrufe wurden auf echte Async-Methoden umgestellt:
 - `IHanaQueryService` ist jetzt async-basiert
 - `HanaQueryService` nutzt `OpenAsync`, `ExecuteReaderAsync`, `ReadAsync`, `ExecuteScalarAsync`
 - Aufrufer wie `HanaDataSourceAdapter`, `StandortePageService` und `SettingsPageService` verwenden keine `Task.Run`-Workarounds mehr fuer HANA
 Damit ist das fruehere Deadlock-/Blocking-Risiko in diesem Pfad deutlich reduziert.
 ### 6. Test- und Build-Stand
 Verifiziert wurde zuletzt mit:
 ```text
 dotnet build .\TrafagSalesExporter.csproj --verbosity minimal
 dotnet test .\TrafagSalesExporter.Tests\TrafagSalesExporter.Tests.csproj --verbosity minimal
 ```
 Ergebnis:
 - Projekt-Build erfolgreich
 - `36/36` Tests gruen
 Bekannt:
 - `dotnet build .\TrafagSalesExporter.sln` endet in dieser Umgebung weiterhin mit Exitcode `1` ohne konkrete Compilerfehler
 - das Hauptprojekt und das Testprojekt bauen aber erfolgreich
 - bekannte Warnungen bleiben:
  - `MSB3270` wegen HANA-Assembly-Architektur
  - MudBlazor-Analyzer zu `Dense`
 ### 7. Aktuelles Architektururteil
 Der Zustand ist jetzt deutlich professioneller als zu Beginn des Refactorings:
 - Datenquellen sauberer getrennt
 - UI konsistenter ueber Page-Services geschnitten
 - groesster Start-/Schema-Block zerlegt
 - HANA-Pfad sicherer und sauberer asynchron
 Aber noch nicht vollendet:
 - keine gezielten Adapter-/Resolver-Unit-Tests
 - keine Retry-Strategie fuer SharePoint / SAP / HANA-Netzpfade
 - kein Secret-Store
 - `DatabaseInitializationService` bleibt trotz Zerlegung ein sensibler produktiver Migrationspfad
 ## Nachtrag 2026-04-17
 Der dokumentierte Stand in diesem Handoff war bei der Waehrungslogik nicht mehr aktuell.
@@ -2,6 +2,100 @@
 Stand: 2026-04-15
 ## Nachtrag 2026-04-17 Refactoring-Fortschritt
 Mehrere frueher als hoch priorisiert markierte Architekturpunkte sind inzwischen bereits umgesetzt.
 Erledigt:
 - DataSourceAdapter-Pattern fuer `HANA`, `SAP_GATEWAY`, `MANUAL_EXCEL`
 - `SiteExportService` deutlich verschlankt
 - Page-Services auf `Scoped`
 - `DatabaseInitializationService` in Schema-/Seed-/Orchestrator-Bloecke getrennt
 - `Dashboard`, `Logs` und `Transformations` von direktem `DbContext`-Zugriff befreit
 - HANA-SQL-Injection-Pfad geschlossen
 - blockierende `.GetAwaiter().GetResult()`-Aufrufe im HANA-Pfad entfernt
 Neuer verifizierter Stand:
 - `dotnet build .\TrafagSalesExporter.csproj --verbosity minimal` erfolgreich
 - `dotnet test .\TrafagSalesExporter.Tests\TrafagSalesExporter.Tests.csproj --verbosity minimal`
 - `36/36` Tests gruen
 ### Neue Top-Prioritaeten ab jetzt
 #### 1. Adapter- und Resolver-Tests nachziehen
 Prio hoch.
 Warum:
 - das neue `DataSourceAdapter`-Pattern ist architektonisch wichtig
 - genau dieser neue Schnitt hat aktuell noch keine gezielten Unit-Tests
 Sinnvoll waeren:
 - `DataSourceAdapterResolver`-Tests
 - `HanaDataSourceAdapter`-Tests
 - `SapGatewayDataSourceAdapter`-Tests
 - `ManualExcelDataSourceAdapter`-Tests
 #### 2. Retry-/Robustheitslayer
 Prio hoch.
 Vor allem fuer:
 - SharePoint
 - SAP Gateway
 - HANA-nahe Netzpfade
 Aktuell brechen diese Integrationen bei transienten Problemen zu direkt ab.
 #### 3. Secret-Store-Konzept
 Prio hoch bis mittel.
 Aktuell liegen Zugangsdaten weiterhin in der App-/DB-Konfiguration.
 Langfristig sollte entschieden werden:
 - Windows Credential Manager
 - DPAPI / verschluesselte Ablage
 - externer Secret Store
 #### 4. `DatabaseInitializationService` weiter haerten, aber nicht mehr blind gross refactoren
 Prio mittel.
 Der schlimmste Architekturteil ist deutlich besser als vorher.
 Weitere Arbeit dort sollte jetzt nur noch zielgerichtet passieren:
 - Regressionstests fuer konkrete Legacy-/Repair-Zustaende
 - spaeter moeglichst versionierte Migrationen
 #### 5. MudBlazor-Analyzer-Warnungen bereinigen
 Prio mittel.
 Nicht kritisch fuer Produktion, aber sinnvoll fuer sauberen Build:
 - `Logs.razor`
 - `Transformations.razor`
 - `Standorte.razor`
 ### Was im Vergleich zu frueher nicht mehr Top-Prioritaet ist
 Nicht mehr ganz oben:
 - generisches weiteres Page-Service-Refactoring um des Refactorings willen
 - noch mehr strukturelles Verschieben ohne Risikoreduktion
 Der wirtschaftlich sinnvolle Fokus liegt jetzt eher auf:
 - Absicherung
 - Robustheit
 - Integrationsstabilitaet
 ## Nachtrag 2026-04-17
 Der Punkt `CHF-Umrechnung / Wechselkurse` ist nicht mehr komplett offen.