# GlobalCube Enterprise Planning, Information & Controlling (gcepic) Das ultimative Tool für: - Forderungsmanagement - Offene Aufträge - Planung - Fahrzeug-Auftragseingang ## Installation Zunächst muss `uv`, der Python-Paketmanager, installiert werden: ```cmd powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` Im Anschluss git-Repository klonen (am Beispiel von Ordner `C:\Projekte` - im Grunde beliebig): ```cmd cd C:\Projekte git clone https://git.global-cube.com/GlobalCube/Reisacher-Forderung.git ``` Git erstellt einen Unterordner `C:\Projekte\Reisacher-Forderung`, in dem das gesamte Projekt abgelegt ist. Jetzt müssen alle Requirements erfüllt werden: passende Python-Version, benötigte Module mit entsprechenden Abhängigkeiten. Das übernimmt `uv` ## Konfiguration ```cmd cd C:\Projekte\Reisacher-Forderung uv sync copy .env.example .env ``` Danach müssen in `.env` die Datenbank-, LDAP-, Proxy- und JWT-Platzhalter ersetzt werden. Danach kann der Webserver gestartet werden: ```cmd .venv\Scripts\activate.bat uvicorn app.main:app --reload --host 0.0.0.0 ``` Die Konsole meldet dann Folgendes: ```txt (Reisacher-Forderung) PS C:\Projekte\Reisacher-Forderung> uvicorn app.main:app --reload --host 0.0.0.0 INFO: Will watch for changes in these directories: ['C:\\Projekte\\Reisacher-Forderung'] INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Started reloader process [41364] using WatchFiles INFO: Started server process [23216] INFO: Waiting for application startup. INFO: Application startup complete. ``` Das Repository ist nun bereit für die Nutzung. ## Nutzung Öffne im Browser. ## Authentifizierung und Deployment Die Anwendung läuft im Produktivbetrieb ausschließlich hinter dem IIS-Reverse-Proxy auf `127.0.0.1:8094`. IIS entfernt einen eventuell vom Client gelieferten Header `X-Remote-User` und setzt ihn nur für erfolgreich per Windows Authentication bestätigte Benutzer neu. Fehlt der Header, bietet die Anwendung die Anmeldung gegen Active Directory über LDAPS an. 1. `migrations/001_authentication.sql` auf der Anwendungsdatenbank ausführen. 2. `.env.example` nach `.env` kopieren und alle Platzhalter ersetzen. 3. Ein eigenes zufälliges `JWT_SECRET` mit mindestens 32 Byte konfigurieren. 4. Das LDAPS-Zertifikat des Domain Controllers auf dem Server als vertrauenswürdig installieren. 5. Die IIS-Proxyadresse in `TRUSTED_PROXY_IPS` eintragen und den FastAPI-Port nicht extern freigeben. 6. Den Windows-Dienst mit `webservice/install_service.bat` installieren. Die Rollenprioritäten sind: Buchhaltung (400), Standortleitung (300), Abteilungsleitung (200) und Mitarbeiter (100). Berechtigungen werden bei jedem Request aus `dbo.Benutzer_Rechte` gelesen; leere Benutzerkennungen erteilen keine Rechte. Tests werden ohne zusätzliche Testabhängigkeiten ausgeführt: ```cmd .venv\Scripts\python.exe -m unittest discover -v ``` ## Filter auf der Forderungsdetailseite Kommentare und Buchungsbelege starten jeweils mit „Diese Rechnung“ und lassen sich unabhängig auf offene Rechnungen, das Fahrzeug oder die gesamte Debitorhistorie erweitern. Die Auswahl gilt für die geöffnete Seite und wird beim Neuladen zurückgesetzt. Die Fahrzeugansicht bleibt auf denselben Debitor begrenzt und ist ohne Fahrzeugnummer deaktiviert. Offen bedeutet `Beleg_offen <> 0`; Zahlungen werden über `Bezug_Beleg_Nr` zugeordnet. Alle Filter bleiben im Mandanten der Ausgangsrechnung. Nach erfolgreicher Rechteprüfung dieser Rechnung umfasst die erweiterte Ansicht ausdrücklich auch andere Standorte und Abteilungen des Debitors. Der direkte Zugriff auf andere Rechnungen wird separat geprüft. Neue Kommentare gehören immer zur geöffneten Rechnung, auch in erweiterten Ansichten. Filterwechsel erhalten ungespeicherte Eingaben. Buchungsbelege sind auf 1.000 Zeilen begrenzt; bei Erreichen dieses Limits erscheint ein Hinweis. Die lesenden Endpunkte `/app/forderungen/details/{primary_key}/kommentare` und `/app/forderungen/details/{primary_key}/buchungen` liefern HTML-Fragmente für HTMX. `scope` akzeptiert `invoice` (Standard), `open`, `vehicle` und `debtor`; andere Werte werden mit HTTP 422 abgelehnt. Kommentar-POSTs übergeben die aktuelle Auswahl als `comment_scope`. Datenbankschemaänderungen sind nicht erforderlich. ## Debug-Anmeldung ohne LDAP Für Entwicklung und manuelle Tests diese Werte in `.env` setzen und die Anwendung neu starten: ```dotenv ENVIRONMENT=development DEBUG_AUTH=true COOKIE_SECURE=false ``` Unter `/login` dieselbe Benutzerkennung in beide Felder eingeben, z. B. Benutzername `winter` und Passwort `winter`. Beide Eingaben müssen exakt übereinstimmen. Die Kennung wird anschließend wie beim AD-Login normalisiert. Eine gültige Zuordnung in `dbo.Benutzer_Rechte` zu einer aktiven Rolle in `dbo.Rollen` ist weiterhin erforderlich; mehrere Berechtigungszeilen werden wie bisher vereinigt. Ein LDAP-Server ist dafür nicht nötig, die konfigurierte SQL-Datenbank und die Authentifizierungsmigration hingegen schon. Im Debugmodus werden IIS-Identitätsheader ignoriert, damit verschiedene Benutzer über das Formular getestet werden können. JWT, CSRF, Logout und die Rechteprüfung pro Request bleiben aktiv; der Token enthält `auth_source=debug`. Benutzername wird als Anzeigename verwendet, E-Mail bleibt leer. Nach dem Deaktivieren von `DEBUG_AUTH` werden diese Tokens nicht mehr akzeptiert. Standardmäßig ist `DEBUG_AUTH=false`; außerhalb der Umgebungen `development`, `debug` und `test` verweigert die Anwendung den Start mit aktivem Debug-Login. `COOKIE_SECURE=false` ist nur für lokale HTTP-Tests gedacht; bei HTTPS auf `true` setzen. ## Darstellung der Forderungsliste Die Filter bleiben vollständig sichtbar und sind in Organisation, Kunde und Beleg sowie Bearbeitung und Wiedervorlage gegliedert. Beim Scrollen der Seite dockt der Tabellenkopf unter der Navigation an; bei schmalen Fenstern lässt sich die Tabelle seitlich verschieben. Kommentare und Antragsinformationen werden je Beleg über „Anzeigen“ eingeblendet. Die Fußleiste zeigt Anzahl und offenen Gesamtbetrag aller gefilterten Treffer, unabhängig von den bereits nachgeladenen Zeilen. Aktive Filter lassen sich dort aufklappen. Auch ohne Treffer bleiben die Filter bedienbar. Die gemeinsamen Gestaltungsregeln liegen in `app.css`, die Ansichten ergänzen `list.css` beziehungsweise `details.css`. ## Rückkehr aus der Detailseite und erneute Anmeldung „Zurück“, „Speichern & Zurück“ und Browser-Zurück laden die Liste frisch, behalten die Filter und führen zur zuvor geöffneten Rechnung. Dazu wird auf der Detailseite eine validierte Listenadresse in `return_to` und auf der Liste die Belegkennung in `focus` mitgeführt. Liegt der Beleg hinter dem ersten Nachladeblock, liefert der erste Aufruf die Zeilen bis einschließlich seines Blocks; danach läuft das Nachladen normal weiter. Ist der Beleg nicht mehr enthalten, bleiben die Filter bestehen und ein Hinweis erscheint. Der Browser hält Rückkehrkontexte getrennt je Tab und Benutzer; es werden keine Kommentare oder Formulareingaben im Browserspeicher abgelegt. Bei abgelaufener Anmeldung führen HTMX-Anfragen nach dem Login auf die vollständige gefilterte Liste beziehungsweise Detailseite. Kommentar- und Buchungsfragmente sowie technische Nachladeseiten sind keine Login-Rücksprungziele. Unterbrochene Schreibaktionen werden nicht automatisch wiederholt; ungespeicherte Eingaben werden nicht gesichert. ## Dokumente im Kommentarbereich Über die Büroklammer oder durch Ablegen auf dem Kommentarfeld können mehrere Dateien beliebigen Typs ausgewählt werden. Die Auswahl mit Name, Größe und Entfernen-Schaltfläche bleibt bis „Abschicken“ ausschließlich im Browser. Kommentartext ist optional; reine Datei-Uploads erzeugen keinen Chat-Eintrag. Beim Verlassen oder Neuladen geht eine noch nicht abgeschickte Auswahl verloren. ```dotenv LOCAL_STORAGE="C:\\Projekte\\Reisacher-Fileserver" UPLOAD_MAX_FILE_SIZE_MB=50 ``` Die Größenbegrenzung gilt je Datei, einschließlich leerer Dateien: 50 MB entsprechen 50 × 1024² = 52.428.800 Bytes. Auswahl und Server prüfen die Grenze. Neue Dateien liegen unter `LOCAL_STORAGE/{Client_DB}_{Beleg_Nr}/{Originalname}`. Altdateien unter `LOCAL_STORAGE/{Client_DB}/{Beleg_Nr}` bleiben sichtbar und herunterladbar; es gibt keine Migration. Unicode-Namen bleiben erhalten. Unter Windows unzulässige Dateinamen werden mit einer Fehlermeldung abgelehnt. Bei Namenskonflikten in beiden Belegordnern wird die ältere Datei in ihrem jeweiligen Ordner als `Name_YYYYMMDD_HHMMSS_ffffff.ext` archiviert (Europe/Berlin, bei Bedarf mit Zähler). Eine prozessübergreifende Belegsperre unter `.upload-locks` schützt die Ablage auch bei mehreren Workern. Dateien werden zuerst unter `.upload-staging` vollständig geschrieben und geprüft; danach erfolgt die Übernahme mit Rücknahme der Archivierung, wenn diese Datei nicht abgelegt werden kann. Diese internen Ordner sind über die Downloadroute nicht erreichbar. Der Ablagepfad darf nicht als öffentliches IIS-Verzeichnis oder als statischer Webpfad freigegeben werden. Das Anwendungskonto benötigt Lesen, Auflisten, Anlegen, Schreiben, Umbenennen und Löschen im Ablagestamm, beiden Belegstrukturen sowie den internen Arbeitsordnern. Für diese Ordner nur den erforderlichen Betriebskonten Zugriff geben. Alle Worker müssen denselben Stamm mit funktionierenden Dateisperren verwenden. Downloads prüfen weiterhin die Belegrechte. Erfolgreiche Dateien bleiben bei Teilerfolgen oder fehlgeschlagener Kommentarspeicherung bestehen. Nur fehlgeschlagene Dateien und nicht gespeicherter Text bleiben zur erneuten Übermittlung in der Auswahl. Nach einer erneuten Anmeldung werden Uploads nicht automatisch wiederholt. Kommentarhistorie und Dateiliste aktualisieren sich ohne Seitenneuladen. Bei IIS `system.webServer/security/requestFiltering/requestLimits/maxAllowedContentLength` (in Bytes) sowie gegebenenfalls vorgeschaltete Proxy- und Hosting-Limits auf die **gesamte** Multipart-Anfrage abstimmen: Anzahl gleichzeitig versandter Dateien × Dateilimit plus Kommentar und Multipart-Overhead. Das Dateilimit ist kein Gesamtlimit. Beispielsweise brauchen vier Dateien à 50 MB mehr als 209.715.200 Bytes; 220.200.960 Bytes (210 MiB) lassen hierfür zusätzlichen Overhead zu. Das übliche IIS-Standardlimit von 30.000.000 Bytes reicht bereits für eine 50-MB-Datei nicht aus. Eine serverseitig mit 413 abgewiesene Anfrage bleibt in der Auswahl; dann weniger Dateien gleichzeitig senden oder das Betriebslimit anpassen. Genügend temporären Speicher auch für den Multipart-Parser des Servers einplanen. Uploadtests verwenden ausschließlich temporäre Verzeichnisse: `python -m unittest discover -s tests -q`.