provisionsmanager95/README.md

Provisions-Manager 95

Windows-Programm der Handy-Insel Miesbach: liest die monatlichen Provisionsabrechnungen von freenet (CSV/Excel) und Vodafone/Euronics (Excel) ein, ordnet die Positionen den Unterhändlern zu, erlaubt freie Anpassung der Auszahlung und exportiert je Händler eine fertige Excel-Abrechnung. Optik: Windows 95.

Installation (Windows)

Provisionsmanager-Setup-<version>.exe aus dem Release herunterladen und starten – keine Admin-Rechte nötig. Das Programm landet in %LOCALAPPDATA%\Programs\Provisionsmanager mit Eintrag im Startmenü (Desktop-Verknüpfung optional) und startet schneller als die einzelne .exe. Ein Update installiert man einfach drüber (ein laufendes Programm wird dafür geschlossen). Deinstallieren über Einstellungen ▸ Apps; Datenbank und Einstellungen in %APPDATA%\Provisionsmanager95 bleiben dabei erhalten. Ohne Installation geht weiterhin Provisionsmanager95.exe (bzw. das .zip) – einfach starten.

Erster Start

Beim ersten Start führt ein Einrichtungs-Assistent durch Speicherort, Unterhändler (inkl. „Nummern aus Abrechnung vorschlagen“) und die erste Abrechnung. Danach zeigt ein Rundgang mit Hinweis-Sprechblasen die wichtigsten Stellen. Beides sowie den Tipp des Tages gibt es jederzeit im Menü ?.

Die Windows-95-Titelleiste ist selbst gezeichnet (Windows lässt die echte nicht umfärben). Falls sie auf einem PC Probleme macht: Datei ▸ Einstellungen ▸ Darstellung – dann wird die normale Windows-Titelleiste verwendet.

Bedienung in Kürze

1. Händler anlegen (Strg+H): Name, Standard-Auszahlung in %, Airtime in % (0 % = keine Airtime) und die Kennungen:

   • freenet → Spalte Unterhaendler (z. B. 11111102)
   • Vodafone → Spalte Vo-Nr (z. B. 80000002, EU000001) oder das Häkchen „Vodafone-Kunden mit Nachnamen in GROSSBUCHSTABEN“: alle Vodafone-Positionen, deren Kundenname komplett großgeschrieben ist (so erfasst unser Unterhändler seine Kunden). Diese Regel kann nur ein Händler haben und hat Vorrang vor der Vo-Nr.
   • Jahresbonus Neuaktivierung: Betrag je Karte nach Staffel, abhängig von der Anzahl Karten des Händlers in der Abrechnung. Standard (änderbar unter Händler ▸ Standard-Staffel Jahresbonus…): 1–9 Karten 5 €, 10–14 10 €, 15–19 15 €, 20–24 20 €, 25–29 25 €, 30–34 30 €, 35–39 35 € je Karte, ab 40 der volle Betrag. Je Händler kann eine eigene Staffel hinterlegt werden. Nie mehr als die Provision laut Abrechnung; Stornos zählen ab. Ein Händler kann mehrere Kennungen haben, auch bei beiden Anbietern. Einzelne Fehltreffer: Positionen markieren → Rechtsklick ▸ Händler zuweisen… (feste Zuweisung, Vorrang vor allem anderen; zurück mit „Automatisch zuordnen“).

2. Neue Abrechnung (Strg+N), z. B. „Oktober 2026“.

3. Import (Strg+I): beliebig viele Dateien auf einmal, z. B. alle freenet-Wochenlisten eines Monats plus die Vodafone-Datei. Das Format wird an der Kopfzeile erkannt. Doppelt importierte Dateien werden erkannt. Unbekannte Kennungen erscheinen unter „(Nicht zugeordnet)“ und lassen sich direkt einem Händler zuordnen.

4. Eigene Filiale ausblenden: Positionen eurer eigenen Kennungen (z. B. freenet 11111100, Vodafone 80000001) müssen nicht verprovisioniert werden. Rechtsklick auf eine nicht zugeordnete Gruppe ▸ Kennung als eigene ausblenden (oder Händler ▸ Eigene Kennungen… bzw. direkt im Import-Bericht). Sie verschwinden aus Liste, Summen und Export und stehen grau unter „(Eigene – ausgeblendet)“. Händler-Zuordnungen (auch GROSSBUCHSTABEN) haben Vorrang.

5. Prüfen und anpassen: links Händler wählen, rechts sind die Positionen nach Provisionsart gruppiert.

   • Gruppe markieren → Prozent… (F4): Auszahlung für die ganze Provisionsart; auf Wunsch als feste Regel für diesen Händler gespeichert (gilt dann für künftige Importe).
   • Doppelklick / F2 auf eine Position: Betrag frei überschreiben (Enter speichern, ↓/Tab nächste Zeile, Esc abbrechen). Blau = von Hand geändert.
   • Rechtsklick: u. a. „Auszahlung 0 €“.

6. Export (Strg+E): je Händler eine .xlsx im Format der Vorlage – freenet und Vodafone zusammen (auf Wunsch getrennt), Airtime nur als eine Summenzeile „Airtime“ – plus eine eigene Airtime-Liste (<Händler> - Airtime - <Titel>.xlsx). Positionen mit 0,00 € werden weggelassen (abschaltbar):

   A	B	C	D	E	F	G	H	I	J	K	L	M	N
   Zeitraum	Provisionsart	Unterhändler-/VO-Nr	Datum	Rufnummer	IMEI	Gerät	Vorname	Name	Tarif	Auszahlung	Netz	Dienst	Aktionscode

   Sortierung: Zeitraum → Provisionsart → Datum, darunter eine Summenzeile. Kopfzeile optional zuschaltbar.

Welche Provisionsart Airtime bzw. Jahresbonus ist, erkennt das Programm an den Texten (z. B. „AirTime Provision“, „Umsatzbeteiligung“, „Jahresbonus“); umstellbar je Provisionsart unter Händler ▸ Provisionsarten….

Das Hauptfenster ist unter Windows ein echtes Programmfenster mit Win95-Optik: an den Bildschirmrand ziehen (Andocken), Win+Pfeiltasten, Doppelklick auf die Titelleiste und Ziehen am Rand funktionieren wie gewohnt.

Zeitraum abrechnen: Im Export-Dialog „Nur von … bis …“ eintragen (oder „Vormonat“; „Noch nicht abgerechnet“ = alles Offene), wahlweise nach Aktivierungsdatum oder Abrechnungszeitraum des Anbieters. Exportierte Positionen werden als abgerechnet gekennzeichnet (grau) und nie wieder exportiert – auch nicht, wenn dieselbe Position später in einer anderen Datei oder Abrechnung auftaucht. Versehentlich? Rechtsklick ▸ Kennzeichnung „abgerechnet“ aufheben. Datei ▸ Abrechnung erledigt / wieder öffnen sperrt eine fertige Abrechnung gegen Änderungen.

Design: Standard ist ein modernes, helles Design (wie Windows 11); das Windows-95-Design gibt es weiter unter Datei ▸ Einstellungen ▸ Darstellung (wirkt nach Neustart).

Linux: Provisionsmanager95-linux-x86_64-<Version>.tar.gz entpacken und Provisionsmanager95 starten (ab Debian 12 / Ubuntu 24.04). Daten liegen unter ~/.config/Provisionsmanager95.

Alles wird sofort in der Datenbank gespeichert (%APPDATA%\Provisionsmanager95\provisionen.db). Speicherort änderbar unter Datei ▸ Einstellungen, Datensicherung über Datei ▸ Datensicherung.

Zuordnung der Vodafone-Spalten

Export	Vodafone/Euronics
Zeitraum	Abrechnungslauf (VF2609, VF2609P8, …)
Provisionsart	Artikelbezeichnung
Unterhändler	Vo-Nr
Datum	Anschaltdatum
Name	Kunde
Tarif	Tarif
Netz	VF / otelo / Cable (aus der Artikelbezeichnung)
Dienst	TarifKey02
Aktionscode	Text

Bei Vodafone wird nur die erste Seite („All“) gelesen – die weiteren Blätter je Abrechnungslauf würden sonst doppelt zählen.

Entwicklung

python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
pytest                                           # Tests (nur erfundene Testdaten)
python -m provtool                               # Programm starten (benötigt Tkinter)

Aufbau:

Datei	Inhalt
provtool/importer.py	Formaterkennung und Einlesen (CSV, xlsx, xls)
provtool/db.py	SQLite: Händler, Kennungen, Regeln, Abrechnungen, Positionen
provtool/export.py	Excel-Export im Zielformat
provtool/money.py	Beträge (intern immer in Cent)
provtool/gui/	Oberfläche (Tkinter im Win95-Stil)
provtool/gui/rahmen.py	selbst gezeichnete Titelleiste, Menüleiste, Größenänderung
provtool/gui/assistent.py	Einrichtungs-Assistent, Rundgang, Tipp des Tages

Datenschutz: Echte Abrechnungen enthalten Kundendaten und gehören nicht ins Repository (.gitignore schließt *.csv, *.xlsx im Hauptordner und beispieldaten/ aus).

Windows-Build

Gitea Actions (.gitea/workflows/windows-build.yml) baut die .exe im Container tobix/pywine:3.12 (Windows-Python unter Wine) mit PyInstaller:

• jeder Push: alle Tests unter Windows-Python (Wine) inklusive Oberflächen-Tests auf einem virtuellen Bildschirm, danach Provisionsmanager95.exe bauen und mit Provisionsmanager95.exe --selbsttest die fertige .exe prüfen; erst dann gibt es das Artefakt
• danach das Setup (build/installer.iss, Inno Setup unter Wine) bauen, still installieren, den Selbsttest in der installierten .exe laufen lassen und still deinstallieren
• Tag vX.Y.Z (passend zu provtool/__init__.py): zusätzlich ein Gitea-Release mit .exe, .zip und Setup

Die Oberflächen-Tests (tests/test_gui.py) bedienen die echte Oberfläche: Dialoge öffnen, Programm schließen, während Assistent/Rückfragen/Rundgang offen sind, Alt+F4, Beträge ändern usw. Jede Ausnahme in der Oberfläche und jeder Eintrag in fehler.log lässt sie fehlschlagen; ein Watchdog bricht hängende Tests ab, statt den Build zu blockieren. Ohne Bildschirm werden sie lokal übersprungen, im Build (PROVTOOL_GUI_TESTS=1) ist das ein Fehler.

Lokal geht dasselbe mit Docker:

docker run --rm --entrypoint bash -v "$PWD":/src -w /src tobix/pywine:3.12 ./build/build_windows.sh

Neue Version: __version__ in provtool/__init__.py erhöhen, committen, git tag v1.0.1 && git push --tags.