Add Alphaplan discovery exporter and finance docs
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user