steve-reporting/README.md

# SteVe Transaction Report Generator

Python script voor het genereren van gedetailleerde rapporten van laadtransacties uit je SteVe OCPP backoffice.

## Installatie

### Vereisten
- Python 3
- MySQL Connector voor Python

### Installeer MySQL Connector

**Optie 1: Via pip (aanbevolen)**
```bash
pip3 install mysql-connector-python --break-system-packages
```

**Optie 2: Via apt**
```bash
sudo apt update
sudo apt install python3-mysql-connector
```

### Script installeren
```bash
# Maak een directory voor het script
mkdir -p ~/reports

# Plaats het script in de directory
# Upload steve_transaction_report.py naar ~/reports/

# Maak het uitvoerbaar
chmod +x ~/reports/steve_transaction_report.py
```

## Gebruik

### Standaard: Alle transacties gedetailleerd
Zonder specifieke opties toont het script de laatste transacties met volledige details:

```bash
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD'
```

Dit toont standaard de laatste 10 transacties met volledige details inclusief verbruik per uur.

### Aantal transacties aanpassen
```bash
# Laatste 5 transacties gedetailleerd
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD' \
  --limit 5

# Laatste 20 transacties gedetailleerd
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD' \
  --limit 20
```

### Compact overzicht (tabel format)
Voor een snel overzicht zonder details:

```bash
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD' \
  --list

# Met meer transacties
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD' \
  --list --limit 20
```

### Specifieke transactie
```bash
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD' \
  --transaction 1
```

### Eenvoudig rapport (zonder uurdetails)
```bash
python3 steve_transaction_report.py \
  --host 192.168.178.201 \
  --port 3307 \
  --password 'JOUW_WACHTWOORD' \
  --transaction 1 \
  --simple
```

## Parameters

| Parameter | Default | Verplicht | Beschrijving |
|-----------|---------|-----------|--------------|
| --host | localhost | Nee | Database server IP of hostname |
| --port | 3306 | Nee | MySQL/MariaDB poort |
| --database | stevedb | Nee | Database naam |
| --user | steve | Nee | Database gebruikersnaam |
| --password | - | **Ja** | Database wachtwoord |
| --list | - | Nee | Toon compact overzicht (tabel) |
| --transaction | - | Nee | Specifieke transactie ID |
| --limit | 10 | Nee | Aantal transacties |
| --simple | - | Nee | Zonder uurdetails |

## Rapport Inhoud

### Gedetailleerd rapport bevat:
- Laadpaal informatie
- Gebruiker en RFID tag
- Start en stop tijden
- Duur van de laadsessie
- Totaal verbruik in kWh
- **Verbruik per uur** met meterwaarden
- Statistieken:
  - Aantal actieve laaduren
  - Gemiddeld verbruik per uur
  - Piekuur (meeste verbruik)
  - Geschatte kosten

### Compact overzicht bevat:
- Transactie ID
- Start datum/tijd
- Duur
- Totaal kWh
- Laadpaal
- RFID tag

## Alias maken (aanbevolen)

Voor gemakkelijk gebruik maak je een alias aan:

```bash
# Voeg toe aan ~/.bashrc
echo "alias steve-report='python3 ~/reports/steve_transaction_report.py --host 192.168.178.201 --port 3307 --user steve --password \"JOUW_WACHTWOORD\"'" >> ~/.bashrc

# Herlaad bashrc
source ~/.bashrc
```

Nu kun je simpel gebruik maken van:

```bash
steve-report                    # Laatste 10 transacties gedetailleerd
steve-report --list             # Compact overzicht
steve-report --limit 5          # Laatste 5 transacties
steve-report --transaction 3    # Specifieke transactie
```

## Voorbeelden

### Voorbeeld 1: Dagelijks overzicht
```bash
steve-report --limit 1
```

### Voorbeeld 2: Wekelijks overzicht
```bash
steve-report --list --limit 50
```

### Voorbeeld 3: Export naar bestand
```bash
steve-report --transaction 5 > laadrapport_$(date +%Y%m%d).txt
```

### Voorbeeld 4: Automatisch dagelijks rapport via cron
```bash
# Voeg toe aan crontab (crontab -e)
# Elke dag om 08:00 uur
0 8 * * * python3 ~/reports/steve_transaction_report.py --host 192.168.178.201 --port 3307 --password 'XXX' --limit 1 > ~/laadrapport_$(date +\%Y\%m\%d).txt
```

### Voorbeeld 5: Rapport via email
```bash
# Installeer mailutils
sudo apt install mailutils

# Voeg toe aan crontab
0 8 * * * python3 ~/reports/steve_transaction_report.py --host 192.168.178.201 --port 3307 --password 'XXX' --transaction 1 | mail -s "Laadrapport" jouw@email.nl
```

## Output Voorbeeld

```
================================================================================
LAADSESSIE RAPPORT - Transactie #1
================================================================================
Laadpaal: VAN_01971
          Alfen Single S-Line thuis
Connector: 1
RFID Tag: 04BB29EAFD0F94
Gebruiker: kors
Start: 28-10-2025 18:27:42
Einde: 29-10-2025 06:12:43
Duur: 11u 45m

Start meterstand: 5518.267 kWh
Eind meterstand: 5540.121 kWh
Totaal geladen: 21.85 kWh
================================================================================

VERBRUIK PER UUR:
--------------------------------------------------------------------------------
Uur                  Start (kWh)     Eind (kWh)      Geladen (kWh)  
--------------------------------------------------------------------------------
28-10 18:27          5518.267        5518.796        0.529          
29-10 01:12          5520.027        5522.945        2.918          
29-10 02:12          5525.658        5529.181        3.523          
29-10 03:12          5531.738        5539.881        8.143          
--------------------------------------------------------------------------------
TOTAAL               5518.267        5540.121        21.854         

================================================================================
STATISTIEKEN:
--------------------------------------------------------------------------------
Actieve laaduren: 4
Gemiddeld per actief uur: 3.78 kWh
Piekuur: 29-10 03:00 (8.14 kWh)

Geschatte kosten (€0.30/kWh): €6.56
Geschatte kosten (€0.10/kWh): €2.19
================================================================================
```

## Troubleshooting

### "Access denied" error
- Controleer of het wachtwoord correct is (gebruik enkele quotes: `'wachtwoord'`)
- Controleer of de gebruiker toegang heeft tot de database
- Test de verbinding: `mysql -h 192.168.178.201 -P 3307 -u steve -p`

### "Can't connect to MySQL server"
- Controleer of host en poort correct zijn
- Controleer of de database server draait
- Controleer firewall instellingen

### "No module named 'mysql.connector'"
Installeer de MySQL connector:
```bash
pip3 install mysql-connector-python --break-system-packages
```

### Geen transacties gevonden
- Controleer of er transacties in de database staan
- Controleer of de database naam correct is (standaard: stevedb)
- Test met: `mysql -h HOST -P PORT -u USER -p -e "SELECT COUNT(*) FROM stevedb.transaction"`

### Speciale tekens in wachtwoord
Gebruik altijd enkele quotes rond het wachtwoord:
```bash
--password 'Mijn$Wachtw00rd!'
```

## Database Structuur

Het script maakt gebruik van de volgende SteVe database tabellen:
- `transaction` - Hoofd transactie gegevens
- `connector_meter_value` - Meterwaarden per tijdstip
- `connector` - Connector informatie
- `charge_box` - Laadpaal informatie
- `user` - Gebruikers
- `ocpp_tag` - RFID tags
- `user_ocpp_tag` - Koppeling tussen gebruikers en tags

## Toekomstige Features

Mogelijke uitbreidingen:
- [ ] Echte prijzen integratie vanuit prijzen database
- [ ] CSV export functionaliteit
- [ ] Grafische weergave van verbruik
- [ ] Vergelijking tussen transacties
- [ ] Maandelijkse/jaarlijkse samenvattingen
- [ ] CO2 besparing berekening

## Support

Voor vragen of problemen:
1. Controleer eerst de troubleshooting sectie
2. Test de database verbinding handmatig
3. Controleer of alle parameters correct zijn

## Licentie

Open source - vrij te gebruiken en aan te passen voor persoonlijk gebruik.

## Versie

Versie 1.1 - Oktober 2025
- Verbeterde prijsberekening
- Standaard gedrag: alle transacties tonen
- --limit werkt overal
- Betere voorbeelden en documentatie