TRMNL – Energia miesięczna (energia_csv)
=======================================

Cel
---
Integracja Home Assistant → TRMNL dla dziennego zużycia energii. Backend buduje CSV i wysyła do TRMNL.
Aktualna logika działa inkrementalnie: pobiera ostatnie 5 dni z HA i scala z danymi już zapisanymi w TRMNL, dzięki czemu starsze dni nie znikają nawet jeśli HA trzyma ~11 dni historii.

Ścieżki i stałe
---------------
- Skrypt uruchamiany przez systemd: /home/gg83/bin/push_energy_csv.sh
- Token HA: /home/gg83/.ha_token
- Service: /etc/systemd/system/push-energy-csv.service
- Timer:   /etc/systemd/system/push-energy-csv.timer
- URL TRMNL pluginu: https://usetrmnl.com/api/custom_plugins/0e9b3c64-9e47-4e91-ba36-594c2409d701
- Strefa czasowa: Europe/Warsaw

Encje Home Assistant
--------------------
- Dzienne:   sensor.tauron_amiplus_590322429801460151_daily_energy_consumption
- Miesięczne:sensor.tauron_amiplus_590322429801460151_monthly_energy_consumption
- Basen:     sensor.pompa_ciepla_energy_daily / sensor.pompa_ciepla_energy_monthly
- Ogrzewanie:sensor.ogrzewanie_dzis_czas_format
- Pogoda:    weather.dom

Jak to działa (wersja bieżąca)
------------------------------
1) Pobranie historii HA z ostatnich 5 dni do północy UTC (minimal_response=true).
2) Agregacja do doby: bierzemy maks z dnia i przesuwamy t-86400 s, żeby kompensować nocne opóźnienie integracji Tauron.
3) Budowa CSV:
   date,kwh
   "YYYY-MM-DD",KWH
4) Merge z tym, co siedzi w TRMNL:
   - scalanie po dacie, nowe wartości nadpisują stare dla tych samych dni,
   - brak kasowania innych pól merge_variables.
5) Uzupełnienie pozostałych pól (jak w v1): dom_wcz_kwh, dom_mies_kwh, basen_dzis_kwh, basen_mies_kwh, ogrz_dzis_txt, weather_temp, weather_condition, updated_at.
6) POST do TRMNL.

Front (TRMNL HTML)
------------------
Parser CSV zachowuje pełną datę YYYY-MM-DD, a wykres filtruje wiersze do bieżącego miesiąca (prefiks YYYY-MM), więc 1 listopada nie nadpisze 1 października. Wykres to słupki 1..N dni miesiąca; brak danych = przerwa.

Systemd (harmonogram)
---------------------
Timer startuje co 30 minut i jest odporny na restarty:
[Timer]
OnBootSec=3min
OnUnitActiveSec=30min
Persistent=true
Unit=push-energy-csv.service

[Service]
Type=oneshot
User=gg83
Group=gg83
ExecStart=/home/gg83/bin/push_energy_csv.sh
WorkingDirectory=/home/gg83

Komendy operacyjne
------------------
Ręczne uruchomienie:
  sudo systemctl start push-energy-csv.service

Podgląd logów:
  journalctl -u push-energy-csv.service -n 50 --no-pager

Status/widoczność timera:
  systemctl list-timers --all | grep push-energy-csv
  systemctl status push-energy-csv.timer

Szybkie sprawdzenie danych w TRMNL:
  curl -s "https://usetrmnl.com/api/custom_plugins/0e9b3c64-9e47-4e91-ba36-594c2409d701" | jq .merge_variables
  curl -s "https://usetrmnl.com/api/custom_plugins/0e9b3c64-9e47-4e91-ba36-594c2409d701" | jq -r '.merge_variables.energia_csv' | awk '/^"/{n++} END{print "Dni:",n}'

Diagnoza problemu „ucina do ~11 dni”
------------------------------------
Przyczyna: Home Assistant /api/history/period zwracał ~11 dni historii dla encji dziennych. Stara wersja skryptu (v1) nadpisywała całe energia_csv świeżym oknem z HA, więc starsze dni wypadały.  
Naprawa: przejście na inkrementalne pobieranie 5 dni + merge po dacie po stronie TRMNL (v2), a następnie przywrócenie aktualizacji pozostałych pól (v2.1).

Historia zmian (ważne)
----------------------
2025-10-08
- Timer zmieniony: z uruchamiania raz dziennie (00:20) na co 30 minut (OnUnitActiveSec=30min, Persistent=true).
- Cel: bieżący podgląd bez opóźnień.

2025-10-09
- Daty do /api/history/period wysyłane w UTC z „Z” na końcu (uniknięcie „Invalid datetime”).
- CSV budowane z przesunięciem -86400 s (flush Tauron po północy).
- minimal_response=true dla szybszej historii.
- Pełne logowanie zakresu i liczby próbek.
- Blokada, aby nie nadpisać TRMNL pustym CSV.
- Nadal pełne NADPISANIE energia_csv (to jeszcze stary model).

2025-10-16 (v2)
- Zmiana strategii: pobieranie ostatnich 5 dni i MERGE z istniejącym energia_csv (koniec z „zjadaniem” początku miesiąca).
- Na tym etapie aktualizowany był tylko energia_csv (timestamp zostawał stary).

2025-10-16 (v2.1)
- Przywrócono aktualizację pozostałych pól: dom_wcz_kwh, dom_mies_kwh, basen_dzis_kwh, basen_mies_kwh, ogrz_dzis_txt, weather_temp, weather_condition.
- Dodano świeży updated_at przy każdym POST.
- Front (HTML) poprawiony: parser trzyma pełną datę i filtruje do bieżącego miesiąca przed rysowaniem.

Weryfikacja „na szybko”
-----------------------
Liczba dni i zakres:
  curl -s "https://usetrmnl.com/api/custom_plugins/0e9b3c64-9e47-4e91-ba36-594c2409d701" \
  | jq -r '.merge_variables.energia_csv' \
  | awk '/^"/{n++} END{print "Dni:",n}'

  curl -s "https://usetrmnl.com/api/custom_plugins/0e9b3c64-9e47-4e91-ba36-594c2409d701" \
  | jq -r '.merge_variables.energia_csv' \
  | awk -F, '/^"/{gsub(/"/,"",$1); print $1}' | sort | sed -n '1p;$p'

Znacznik czasu:
  curl -s "https://usetrmnl.com/api/custom_plugins/0e9b3c64-9e47-4e91-ba36-594c2409d701" \
  | jq -r '.merge_variables.updated_at'

Uwagi końcowe
-------------
- Jeśli kiedyś zechcesz, by backend trzymał TYLKO bieżący miesiąc (a nie wiele miesięcy w jednym CSV), można dodać prosty filtr po prefiksie YYYY-MM po scaleniu. Front już filtruje, więc nie jest to wymagane.
- Blokada flock zabezpiecza przed równoległymi runami timera.
- Jeśli HA nie zwraca danych (pusta historia), skrypt nie nadpisuje TRMNL pustym CSV.