Stephan Schellworth ea566c270f docs: add gateway docs and Cursor plan artifacts

Made-with: Cursor

2026-04-22 07:21:43 +02:00

8.1 KiB

Raw Permalink Blame History

Preprocessor Assessment -- Althaus Bot v2

Zweck: Technische Analyse des Preprocessing-Servers für die Aufwandsschätzung der Erweiterungen
Erstellt: 13. April 2026
Quellen: Gateway-Code-Analyse (Repo nicht lokal verfügbar: github.com/valueonag/gateway_preprocessing)

1. Ist-Zustand (abgeleitet aus Gateway-Code)

1.1 Infrastruktur

Eigenschaft	Wert
Host	Azure App Service (Switzerland North)
URL (Datenverarbeitung)	`poweron-althaus-preprocess-prod-*.azurewebsites.net/api/v1/dataprocessor/update-db-with-config`
URL (Abfragen)	`poweron-althaus-preprocess-prod-*.azurewebsites.net/api/v1/dataquery/query`
Authentifizierung	`X-PP-API-Key` (Abfragen) / `X-DB-API-Key` (Abfragen)
Status	Deployed, ERP-Datenanbindung deaktiviert
Quellcode	`github.com/valueonag/gateway_preprocessing` (separates Repo)

1.2 Aktuelle Tabellen-Konfiguration

Aus dem Automation-Template (subAutomationTemplates.py) extrahiert:

{
  "tables": [
    {
      "name": "Artikel",
      "powerbi_table_name": "Artikel",
      "steps": [
        {
          "keep": {
            "columns": [
              "I_ID", "Artikelbeschrieb", "Artikelbezeichnung",
              "Artikelgruppe", "Artikelkategorie", "Artikelkürzel",
              "Artikelnummer", "Einheit", "Gesperrt",
              "Keywords", "Lieferant", "Warengruppe"
            ]
          }
        },
        {
          "fillna": {
            "column": "Lieferant",
            "value": "Unbekannt"
          }
        }
      ]
    },
    {
      "name": "Einkaufspreis",
      "powerbi_table_name": "Einkaufspreis",
      "steps": [
        {
          "to_numeric": {
            "column": "EP_CHF",
            "errors": "coerce"
          }
        },
        {
          "dropna": {
            "subset": ["EP_CHF"]
          }
        }
      ]
    }
  ]
}

1.3 Zusätzliche Tabellen (im Chatbot referenziert, aber nicht in der Config)

Aus den SQL-Beispielen in bridges/tools.py und chatbot.py:

Tabelle	Spalten (referenziert im Code)	Joins
`Lagerplatz_Artikel`	`R_ARTIKEL`, `R_LAGERPLATZ`, `S_IST_BESTAND`, `S_RESERVIERTER__BESTAND`	ON `Artikel.I_ID = Lagerplatz_Artikel.R_ARTIKEL`
`Lagerplatz`	`I_ID`, `Lagerplatz` (Name)	ON `Lagerplatz_Artikel.R_LAGERPLATZ = Lagerplatz.I_ID`

Diese Tabellen sind vermutlich in einer älteren Config-Version oder direkt im Preprocessor konfiguriert.

1.4 API-Schnittstellen

Abfrage-API (genutzt vom PreprocessorConnector):

Methode: POST
Payload: {"query": "SELECT ..."}
Header: X-DB-API-Key: <api_key>
Response: {"success": true/false, "data": [...], "row_count": N, "message": "..."}
Einschränkung: Nur SELECT-Queries (validiert im Gateway)

Update-API (genutzt vom Automation-Template):

Methode: POST
Payload: configJson (Tabellendefinitionen + Transformationsschritte)
Header: X-PP-API-Key: <secret>
Zweck: Datenbank mit neuer Konfiguration aktualisieren

1.5 Transformation-Steps (bekannte Operationen)

Aus der Config-JSON abgeleitet:

Operation	Parameter	Beschreibung
`keep`	`columns: [...]`	Nur angegebene Spalten behalten
`fillna`	`column`, `value`	NULL-Werte ersetzen
`to_numeric`	`column`, `errors`	Spalte in numerischen Typ konvertieren
`dropna`	`subset: [...]`	Zeilen mit NULL in angegebenen Spalten entfernen

2. Benötigte Erweiterungen (nach Position)

2.1 Position 1.5: Kundenartikelnummern

Neue Tabelle: Kundenartikelnummer

Spalte (geschätzt)	Typ	Beschreibung
`I_ID`	INT	Primary Key
`R_ARTIKEL`	INT	FK auf Artikel.I_ID
`Kundenummer`	VARCHAR	Kundennummer
`Kundenartikelnummer`	VARCHAR	Kunden-eigene Artikelnummer
`Bezeichnung`	VARCHAR	Kundenbezeichnung (optional)

Config-Erweiterung:

{
  "name": "Kundenartikelnummer",
  "powerbi_table_name": "Kundenartikelnummer",
  "steps": [
    {"keep": {"columns": ["I_ID", "R_ARTIKEL", "Kundenummer", "Kundenartikelnummer", "Bezeichnung"]}}
  ]
}

Aufwand-Bewertung: Falls der Preprocessor neue Tabellen per Config akzeptiert: ~2-3h Config + Test. Falls neuer Code nötig: ~6-8h.

2.2 Position 3.1: Bestellwesen (Materialmanagement 1)

Neue Tabellen (geschätzt 3-4 Tabellen):

Tabelle	Wichtige Spalten	Zweck
`Bestellkopf`	ID, Bestellnummer, Lieferant, Bestelldatum, Status, Wunschtermin	Bestellübersicht
`Bestellposition`	ID, R_Bestellung, R_Artikel, Menge, Preis, Status, Bestätigter_Termin	Positionsdetails
`Wareneingang`	ID, R_Bestellung, R_Position, Eingangsdatum, Menge, Qualität	Lieferverfolgung
`Auftrag`	ID, Auftragsnummer, Kunde, R_Artikel, Menge, Termin	Betroffene Aufträge

Aufwand-Bewertung: 4 Tabellen × ~4h pro Tabelle (Config + Code + Transformationen + Test) = ~16h. Bei komplexen Transformationen (Joins, Aggregationen): +4-6h.

2.3 Position 4.1: KPI-Daten (Materialmanagement 2)

Neue Tabellen/Views (geschätzt 3-4):

Tabelle/View	Wichtige Spalten	Zweck
`Lagerjournal`	ID, R_Artikel, Buchungsdatum, Menge, Typ	Lagerbewegungen
`Preishistorie`	ID, R_Artikel, R_Lieferant, Datum, Preis, Währung	Preisentwicklung
`Bestandesbedarfsliste`	R_Artikel, Bedarf, Bestand, Fehlmenge, Datum	Dispositionsplanung
`View_Termintreue`	R_Lieferant, Wunschtermin, Bestätigt, Geliefert, Abweichung_Tage	Aggregierte KPIs

Aufwand-Bewertung: 4 Tabellen/Views × ~4h = ~16h. Aggregierte Views (Termintreue): +4-6h für Berechnungslogik im Preprocessor.

3. Gesamtbewertung Preprocessor-Erweiterungen

3.1 Zusammenfassung

Position	Neue Tabellen	Config-Aufwand	Code-Aufwand	Test	Gesamt
1.5 (Kundenartikelnummern)	1	1h	3-5h	2h	6-8h
3.1 (Bestellwesen)	3-4	2h	8-12h	4h	14-18h
4.1 (KPIs)	3-4	2h	8-12h	4h	14-18h
Gesamt	7-9	5h	19-29h	10h	34-44h

3.2 Offene Fragen (Code-Review des Preprocessor-Repos erforderlich)

#	Frage	Auswirkung
P1	Unterstützt der Preprocessor neue Tabellen per Config-Erweiterung, oder muss für jede Tabelle Code geschrieben werden?	Bestimmt ob Config-only (~2h/Tabelle) oder Code (~4h/Tabelle)
P2	Können aggregierte Views/Berechnungen im Preprocessor definiert werden?	Termintreue-KPI, Bestandsreichweite
P3	Wie werden Joins zwischen Tabellen gehandhabt? (SQLite-seitig oder Preprocessor-seitig)	Komplexität der Cross-Table-Queries
P4	Gibt es Rate-Limits oder Grössen-Limits bei der Query-API?	Performance bei komplexen KPI-Abfragen
P5	Wie gross ist die aktuelle SQLite-Datenbank? Wie viele Artikel?	Dimensionierung für 8-10 neue Tabellen

3.3 Empfehlung

Vor Projektstart sollte ein Code-Review des Preprocessor-Repos durchgeführt werden (geschätzter Aufwand: 2-4h). Dabei klären:

Erweiterbarkeit: Kann der Preprocessor neue Tabellen per Config akzeptieren?
Transformationen: Welche Operationen sind neben keep, fillna, to_numeric, dropna verfügbar?
Performance: Wie skaliert die SQLite-DB mit 8-10 zusätzlichen Tabellen?
Deployment: Wie wird der Preprocessor deployed? (CI/CD, manuell, Azure DevOps)

Das Ergebnis dieses Reviews kann die Aufwandsschätzung für Pos. 1.5, 3.1 und 4.1 um jeweils 4-6h nach oben oder unten korrigieren.

4. Aktueller Datenfluss (zur Referenz)

ERP (Althaus)
    │
    ▼ (Power BI Export / API / DB-Zugriff -- Mechanismus unklar)
Preprocessor Server (Azure)
    │
    ├── /api/v1/dataprocessor/update-db-with-config  ← Automation-Template
    │   (Tabellen laden, transformieren, in SQLite schreiben)
    │
    └── /api/v1/dataquery/query  ← PreprocessorConnector (Gateway)
        (SQL SELECT auf SQLite ausführen)
    │
    ▼
Gateway (Chatbot LangGraph)
    │
    ▼
React Frontend (Chat-UI)

Assessment erstellt auf Basis der Gateway-Code-Analyse. Für eine genauere Schätzung ist ein Code-Review des Preprocessor-Repos erforderlich.

8.1 KiB Raw Permalink Blame History Unescape Escape