# 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 % und die *Kennungen*:
   - freenet → Spalte **Unterhaendler** (z. B. `27518902`)
   - Vodafone → Spalte **Vo-Nr** (z. B. `80211721`, `EU133301`) **oder**
     „Vodafone (Name 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.
   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. **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 €“.
5. **Export** (`Strg+E`): je Händler (und je Anbieter) eine `.xlsx` im Format der Vorlage:

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

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