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.

## 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.

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

```bash
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
- Tag `vX.Y.Z` (passend zu `provtool/__init__.py`): zusätzlich ein Gitea-Release mit `.exe` und `.zip`

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:

```bash
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`.