Statistiky a historia jazd

Migrovane z docs-old-cvrn/plans/PLAN_STATISTIKY.md.

0) Stav realizacie (aktualizovane 2026-02-08)

Hotovo

• Pridana route /stats.
• Pridane tlacidlo Statistiky v hlavicke vedla dark mode toggle.
• Implementovany 1. graf: denny prehlad vypoziciek za aktualny mesiac.
• Implementovany 2. graf: vypozicky podla bicykla za aktualny mesiac (5 bicyklov).
• Napojenie na realne data z DB cez stats RPC.
• Revalidacia /stats po rent a return akcii.
• SQL patch pre existujuce prostredie: supabase/patches/003_add_stats_rpc.sql.

Zostava

• Period switcher mesiacov/obdobia (napr. 7/30/90 alebo prepinanie mesiacov).
• User-specific sekcia (Moje jazdy, moje KPI, historia mojich jazd).
• Pie chart / pokrocilejsie komunitne vizualizacie.
• Dokoncit testovanie podla checklistu a doplnit regression scenare.

1) Ciel

Pridat samostatnu podstranku statistik, kde budu:

• komunitne statistiky poziciavania bicyklov,
• individualne statistiky pre konkretneho pouzivatela,
• prepinac obdobia 7 dni / 30 dni / 90 dni,
• vizualizacie cez area/bar/pie chart,
• tabulka historie jazd pre usera.

2) Scope

In scope

• nova route /stats,
• globalne agregacie (bez osobnych udajov inych userov),
• user-specific agregacie (len pre prihlaseneho usera),
• "KPI" summary karty na vrchu,
• responsive chart layout pre desktop aj mobile.

Out of scope (v tejto etape)

• export do CSV/PDF,
• prediktivne forecasty,
• realtime websocket update (staci refresh/reload),
• heatmapa podla mapy/stanovist (to pride po mape).

3) UX navrh (decision-complete)

3.1 Navigacia

• Do header menu pridat link Statistiky -> /stats.
• Pristup:
  • allowlisted user: ano,
  • neallowlisted user: stale not-authorized,
  • admin: ano (plus mozne extra bloky neskor).

3.2 Layout stranky /stats

1. Hlavicka:
   • title Statistiky,
   • period switcher: 7 dni, 30 dni, 90 dni.
2. KPI riadok:
   • Total vypoziciek (za obdobie),
   • Unikatni pouzivatelia (za obdobie, global),
   • Moje vypozicky (za obdobie).
3. Taby:
   • Komunitne,
   • Moje jazdy.

3.3 Komunitne grafy

1. Area chart - "Pozicky za den":
   • osa X: datum,
   • osa Y: pocet vypoziciek,
   • serie: bike1..bike5 (5 serii).
2. Bar chart - "Vypozicky podla bicykla":
   • 5 stlpcov (bike1..bike5),
   • hodnota = total rentals za obdobie.
3. Pie chart - "Podiel bicyklov":
   • percenta pouzitia bicyklov za obdobie.

3.4 Moje jazdy

1. Moje KPI:
   • Moje vypozicky,
   • Priemerna dlzka jazdy,
   • Najcastejsi bicykel.
2. Area alebo bar chart "Moje vypozicky za den".
3. Tabulka "Historia mojich jazd":
   • datum,
   • bicykel,
   • cas pozicania,
   • cas vratenia,
   • dlzka jazdy (minutes/hours),
   • return note (ak existuje).

4) Datovy model a SQL dopady

Aktualny model to podporuje z rentals, bikes, profiles. Nie je nutna nova tabulka pre MVP statistik.

4.1 Doporucene indexy

Pridat indexy pre rychle agregacie:

• rentals(rented_at)
• rentals(user_id, rented_at)
• rentals(bike_id, rented_at)
• rentals(returned_at) (optional)

4.2 Casove pravidla

• den sa pocita podla timezone Europe/Bratislava (default),
• agregacia podla rented_at (vypozicka vznikla v danom dni).

5) API / RPC plan

Prehlad funkcii (Supabase RPC):

1. stats_get_global_kpi(range_days int, tz text default 'Europe/Bratislava')
   • vrati:
     • total_rentals,
     • unique_users,
     • avg_ride_minutes.
2. stats_get_daily_by_bike(range_days int, tz text default 'Europe/Bratislava')
   • vrati riadky:
     • day date,
     • bike_id,
     • bike_name,
     • rentals_count.
3. stats_get_totals_by_bike(range_days int)
   • vrati:
     • bike_id,
     • bike_name,
     • rentals_count.
4. stats_get_my_kpi(range_days int, tz text default 'Europe/Bratislava')
   • vrati:
     • my_total_rentals,
     • my_avg_ride_minutes,
     • my_top_bike.
5. stats_get_my_daily(range_days int, tz text default 'Europe/Bratislava')
   • vrati:
     • day,
     • rentals_count.
6. stats_get_my_history(range_days int, limit_count int, offset_count int)
   • vrati paginovanu historiu jazd pre usera.

6) RLS a privacy

Pravidla:

• Globalne statistiky su agregovane, bez zoznamu cudzich userov.
• User-specific data vracaju iba zaznamy auth.uid().
• Admin-only rozsirenie (optional neskor):
  • top users, user ranking, detail pre fleet management.

Bezpecnost:

• ziadne raw secret_code sa do statistik nedostane,
• ziadne emaily inych userov v community grafoch.

7) Frontend implementacny navrh

7.1 Technologie

• Pouzit recharts (rovnaky engine ako shadcn chart examples).
• UI kontajnery:
  • existujuce Card, Badge, Table, Button.
• Volitelne:
  • pridat jednoduche chart wrapper komponenty do src/components/ui/chart.tsx podla shadcn vzoru.

7.2 Nove subory

• src/app/stats/page.tsx
• src/app/stats/_components/period-switcher.tsx
• src/app/stats/_components/community-area-chart.tsx
• src/app/stats/_components/community-bar-chart.tsx
• src/app/stats/_components/community-pie-chart.tsx
• src/app/stats/_components/my-history-table.tsx
• src/lib/stats/transformers.ts

7.3 Data flow

1. stats/page.tsx nacita period (7/30/90) zo search param.
2. Server-side vola RPC paralelne (global + my data).
3. Data sa transformuju do chart-friendly formatu.
4. Komponenty vykreslia grafy + tabulku.
5. Pri zmene period switcheru sa refreshne URL query (?period=30d).

8) Performance plan

• Dotazy obmedzit na max 90 dni v MVP.
• Pouzit agregaciu v SQL, nie v JS.
• Limit pre user history tabulku:
  • default 50 riadkov + pagination.
• Ak data narastu:
  • pridat materialized view pre daily aggregates.

9) Test plan

9.1 Funkcne

1. Period switch:
   • 7d, 30d, 90d meni hodnoty grafov a KPI.
2. Community area chart:
   • den s 0 vypozickami zobrazi 0.
3. Bar chart:
   • sucty sedi s area agregaciou.
4. Pie chart:
   • percenta dava zmysel, suma ~100%.
5. My history:
   • user vidi len svoje jazdy.

9.2 Security

1. Bezny user nevidi emaily cudzich userov.
2. Bezny user nevie cez URL parameter nacitat cudziu historiu.
3. Neautentifikovany user nema pristup na /stats.

9.3 Regression

• overit checklist v docs/checklist.md:
  • login,
  • rent,
  • return,
  • admin flow stale funguje.

10) Rollout plan

Faza 1: Data API

• Pridat indexy + SQL RPC.
• Otestovat SQL manualne na test data.

Faza 2: MVP stats page

• Pridat /stats:
  • period switcher,
  • KPI cards,
  • 1 area chart + my history table.

Faza 3: Full visual pack

• Dodat bar + pie chart.
• Dostat layout do mobile/desktop parity.

Faza 4: Admin extensions (optional)

• Fleet metrics pre admin:
  • top users,
  • utilizacia bicyklov,
  • nevratene jazdy > X hodin.

11) Open decisions (defaults nastavene)

1. Kto vidi /stats?
   • default: vsetci allowlisted useri.
2. Kde budu "user-specific" cisla?
   • default: v sekcii Moje jazdy.
3. Predvolene obdobie?
   • default: 30 dni.
4. Timezone?
   • default: Europe/Bratislava.
5. Ma byt /stats aj v admin?
   • default: jedna spolocna route s extra admin blockmi neskor.

12) Minimalny backlog (implementacne poradie)

1. SQL indexy + stats RPC pre aktualny mesiac.
2. Stranka /stats (bez period switchera v tejto faze).
3. Community graf: denny prehlad + summary metriky.
4. My KPI + my history table.
5. ~ Bar chart hotovy, pie chart este chyba.
6. Aktualizacia docs/checklist.md o stats-specific test cases.

13) Kompatibilita s planom reported bicykla

Po implementacii planu PLAN_NAHLASENE_NEPOZICATELNE_BIKY.md je vhodne zvazit optional KPI pre fleet zdravie:

• pocet bicyklov v stave reported,
• trend novych reportov za obdobie (napr. 7/30/90 dni),
• priemerny cas od reportu po resolve.

Toto nie je blokujuca zavislost pre aktualny stats scope, iba backlog rozsireni.