From 2e1bb4feff69f63afb7ed401d44094246315e6c9 Mon Sep 17 00:00:00 2001
From: Agent <agent@tpsoft.org>
Date: Tue, 29 Sep 2026 12:42:38 +0200
Subject: [PATCH] Add implementation steps

---
 docs/steps.md | 488 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 488 insertions(+)
 create mode 100644 docs/steps.md

diff --git a/docs/steps.md b/docs/steps.md
new file mode 100644
index 0000000..3b6f553
--- /dev/null
+++ b/docs/steps.md
@@ -0,0 +1,488 @@
+# TimeLog – kroky implementácie
+
+Tento dokument rozdeľuje implementáciu aplikácie TimeLog na samostatné, postupne realizovateľné kroky.
+
+Vychádza zo súboru `docs/specification.txt`. Jednotlivé kroky sú zámerne navrhnuté tak, aby sa dali neskôr rozpracovať do samostatných promptov pre implementačného agenta.
+
+## Zásady implementácie
+
+- Postupovať po krokoch v uvedenom poradí, pokiaľ konkrétny krok výslovne neumožňuje paralelnú implementáciu.
+- Každý krok má skončiť funkčným a overiteľným stavom projektu.
+- Nepoužívať externé knižnice.
+- Backend implementovať v PHP.
+- Frontend implementovať v HTML, CSS a čistom JavaScripte.
+- Dáta ukladať do JSON súborov mimo verejného webrootu.
+- `public/` musí byť jediný verejne dostupný adresár.
+- Aplikácia musí byť navrhovaná mobile-first, ale použiteľná aj na desktope.
+- Pri implementácii zachovať pravidlá a dátové štruktúry definované v `docs/specification.txt`.
+- Funkcionalitu mimo prvej verzie, napríklad export dát alebo offline režim, zatiaľ neimplementovať.
+
+---
+
+## Krok 1 – Základná kostra projektu
+
+Vytvoriť adresárovú a súborovú štruktúru projektu podľa špecifikácie.
+
+Pripraviť najmä:
+
+- `public/`
+- `public/assets/css/`
+- `public/assets/js/`
+- `public/assets/icons/`
+- `src/`
+- `src/controllers/`
+- `src/views/`
+- `data/`
+- `data/days/`
+- `var/logs/`
+- `var/sessions/`
+- `tests/`
+
+Vytvoriť základný vstupný bod `public/index.php`, bootstrap aplikácie a konfiguráciu.
+
+Cieľom kroku ešte nie je implementovať funkcionalitu, ale pripraviť čistý základ, na ktorom budú stavať ďalšie kroky.
+
+### Výsledok
+
+Po otvorení aplikácie cez webserver sa zobrazí jednoduchá základná stránka a PHP aplikácia sa korektne inicializuje.
+
+---
+
+## Krok 2 – JSON úložisko a bezpečná práca so súbormi
+
+Implementovať všeobecnú triedu `JsonStore`, cez ktorú bude aplikácia čítať a zapisovať JSON dáta.
+
+Riešiť:
+
+- načítanie JSON súboru,
+- vytvorenie súboru, ak ešte neexistuje,
+- validáciu chybného JSON,
+- bezpečný zápis,
+- ochranu pred poškodením dát pri zápise,
+- zamykanie súborov pri zápise,
+- vytvorenie potrebných dátových adresárov.
+
+Táto vrstva má byť spoločným základom pre používateľov, činnosti aj udalosti.
+
+### Výsledok
+
+Aplikácia má jednu spoľahlivú vrstvu pre čítanie a zápis JSON dát a ostatné časti aplikácie nemusia pracovať so súbormi priamo.
+
+---
+
+## Krok 3 – Používatelia, autentifikácia a session
+
+Implementovať:
+
+- `UserRepository`,
+- `Auth`,
+- `AuthController`,
+- prihlasovací formulár,
+- PHP session,
+- odhlásenie,
+- ochranu všetkých privátnych obrazoviek.
+
+Používatelia budú uložení v `data/users.json`.
+
+Heslá ukladať výhradne cez `password_hash()` a kontrolovať cez `password_verify()`.
+
+V tejto fáze zabezpečiť spôsob vytvorenia prvého používateľa, aby bolo možné aplikáciu po čistej inštalácii začať používať.
+
+### Výsledok
+
+Neprihlásený používateľ sa nedostane do aplikácie. Platný používateľ sa môže prihlásiť a odhlásiť.
+
+---
+
+## Krok 4 – Repository a správa činností
+
+Implementovať `ActivityRepository` a dátový súbor `data/activities.json`.
+
+Pripraviť základné činnosti zo špecifikácie:
+
+- Spánok,
+- Práca,
+- Jedlo,
+- Oddych,
+- Domácnosť,
+- Presun,
+- Nakupovanie,
+- Pošta,
+- Hygiena,
+- Iné.
+
+Každá činnosť musí mať minimálne:
+
+- ID,
+- názov,
+- farbu.
+
+Implementovať obrazovku správy činností:
+
+- zoznam,
+- pridanie,
+- úprava názvu,
+- úprava farby,
+- možnosť činnosť skryť alebo deaktivovať bez poškodenia historických dát.
+
+### Výsledok
+
+Používateľ môže spravovať činnosti a zmeny sa ukladajú do JSON.
+
+---
+
+## Krok 5 – Repository udalostí
+
+Implementovať `EventRepository` pre prácu so súbormi `data/days/YYYY-MM-DD.json`.
+
+Repository musí podporovať:
+
+- získanie udalostí dňa,
+- pridanie udalosti,
+- úpravu udalosti,
+- vymazanie udalosti,
+- automatické zoradenie podľa času,
+- odmietnutie dvoch udalostí s rovnakým časom v rovnakom dni,
+- spätné pridanie udalosti do historického dňa,
+- `createdAt`,
+- `createdBy`,
+- `updatedAt`,
+- `updatedBy`.
+
+Pri operáciách overovať existenciu použitého `activityId`.
+
+### Výsledok
+
+Backend vie spoľahlivo vykonávať CRUD operácie nad udalosťami jednotlivých dní.
+
+---
+
+## Krok 6 – Výpočet časových úsekov dňa
+
+Implementovať `TimeCalculator`.
+
+Toto je samostatný doménový krok bez závislosti od vizuálneho zobrazenia.
+
+Z udalostí musí vytvoriť časové úseky činností a správne vyriešiť:
+
+- interval medzi dvoma udalosťami,
+- čas od 00:00 po prvú udalosť,
+- prevzatie poslednej činnosti z predchádzajúceho dňa,
+- predvolenú činnosť Spánok, ak predchádzajúca udalosť neexistuje,
+- pokračovanie činnosti cez polnoc,
+- posledný úsek aktuálneho dňa po aktuálny čas,
+- posledný úsek historického dňa do 24:00,
+- deň bez vlastných udalostí.
+
+Výsledkom má byť normalizovaný zoznam úsekov s časom začiatku, konca, trvaním a `activityId`.
+
+### Výsledok
+
+Existuje jedna centrálna implementácia výpočtu času, ktorú neskôr použije denný aj týždenný prehľad.
+
+---
+
+## Krok 7 – Testy TimeCalculator a dátovej vrstvy
+
+Pred tvorbou reportov doplniť testy kritických pravidiel.
+
+Minimálne scenáre:
+
+- bežné dve a viac udalostí počas dňa,
+- prvá udalosť až ráno,
+- prevzatie činnosti z predchádzajúceho dňa,
+- práca cez polnoc,
+- prvý evidovaný deň bez predchádzajúcich dát,
+- deň bez udalostí,
+- aktuálny deň,
+- historický deň,
+- duplicitný čas udalosti,
+- zoradenie spätne pridanej udalosti,
+- úprava času udalosti,
+- vymazanie udalosti.
+
+Testy majú byť spustiteľné bez externého testovacieho frameworku, ak by jeho použitie odporovalo požiadavke nepoužívať externé knižnice.
+
+### Výsledok
+
+Najdôležitejšie výpočtové a dátové pravidlá sú automaticky overiteľné.
+
+---
+
+## Krok 8 – Hlavná obrazovka pre rýchle zaznamenanie činnosti
+
+Implementovať hlavnú mobilnú obrazovku aplikácie.
+
+Zobraziť veľké, ľahko stlačiteľné tlačidlá aktívnych činností.
+
+Po kliknutí na činnosť otvoriť jednoduchý formulár obsahujúci:
+
+- vybranú činnosť,
+- aktuálny čas ako predvolenú hodnotu,
+- možnosť čas upraviť,
+- OK,
+- ZRUŠIŤ.
+
+Po potvrdení uložiť udalosť pre aktuálny deň.
+
+Zobraziť zrozumiteľnú chybu pri duplicitnom čase alebo neplatnom vstupe.
+
+### Výsledok
+
+Základný každodenný workflow aplikácie – zaznamenanie začiatku novej činnosti – funguje na pár kliknutí z mobilu.
+
+---
+
+## Krok 9 – Detail dňa a správa udalostí
+
+Implementovať obrazovku zvoleného dňa.
+
+Umožniť:
+
+- zobraziť aktuálny deň,
+- prejsť na predchádzajúci alebo nasledujúci deň,
+- vybrať historický deň,
+- zobraziť zoznam udalostí,
+- spätne pridať udalosť,
+- upraviť čas udalosti,
+- zmeniť činnosť udalosti,
+- vymazať udalosť.
+
+Pri každej zmene sa musí následne prepočítať celý deň.
+
+### Výsledok
+
+Používateľ môže spätne opraviť alebo doplniť svoju časovú evidenciu.
+
+---
+
+## Krok 10 – Vizuálna časová os dňa
+
+Nad výsledkami `TimeCalculator` vytvoriť vizuálnu časovú os.
+
+Mobil:
+
+- vertikálna časová os,
+- farebné obdĺžniky pod sebou,
+- veľkosť úseku primeraná jeho trvaniu.
+
+Desktop:
+
+- horizontálna časová os,
+- farebné úseky zľava doprava.
+
+Farby čerpať z definície činností.
+
+Časová os musí korektne zobrazovať aj dopočítané úseky pred prvou a po poslednej udalosti.
+
+### Výsledok
+
+Používateľ na prvý pohľad vidí, ako bol jeho deň časovo rozdelený.
+
+---
+
+## Krok 11 – Denný sumár
+
+Z časových úsekov vypočítať sumár dňa podľa `activityId`.
+
+Zobraziť:
+
+- názov činnosti,
+- farbu,
+- celkové trvanie v hodinách a minútach.
+
+Do sumáru zahrnúť aj dopočítané úseky.
+
+Súčet pre historický kompletný deň musí predstavovať 24 hodín. Pri aktuálnom dni má zodpovedať času od 00:00 po aktuálny čas.
+
+### Výsledok
+
+Detail dňa obsahuje vizuálnu časovú os aj presný sumár času podľa činností.
+
+---
+
+## Krok 12 – Týždenný prehľad a sumár
+
+Implementovať `ReportController` a týždennú obrazovku.
+
+Týždeň začína v pondelok.
+
+Implementovať:
+
+- aktuálny týždeň,
+- navigáciu medzi týždňami,
+- zobrazenie jednotlivých dní,
+- preklik na detail dňa,
+- výpočet každého dňa cez rovnaký `TimeCalculator`,
+- agregáciu trvania podľa `activityId`,
+- týždenný sumár.
+
+Pri pondelku správne zohľadniť poslednú udalosť z nedele pred začiatkom zobrazovaného týždňa.
+
+Pri aktuálnom týždni nezapočítavať budúci čas.
+
+### Výsledok
+
+Používateľ vidí rozdelenie svojho času za celý týždeň a môže prejsť na ktorýkoľvek konkrétny deň.
+
+---
+
+## Krok 13 – Správa používateľských loginov
+
+Implementovať obrazovku správy používateľov.
+
+Podporovať:
+
+- zoznam loginov,
+- vytvorenie loginu,
+- zmenu hesla,
+- aktiváciu/deaktiváciu podľa potreby,
+- ochranu pred deaktivovaním posledného aktívneho loginu.
+
+Verejnú registráciu nevytvárať.
+
+Všetky login-y pracujú s rovnakými dátami.
+
+### Výsledok
+
+Vlastník aplikácie môže kompletne spravovať prihlasovacie účty priamo z aplikácie.
+
+---
+
+## Krok 14 – Responzívne UI a spoločný layout
+
+Zjednotiť vzhľad aplikácie a dokončiť mobile-first responzívny layout.
+
+Riešiť:
+
+- spoločnú navigáciu,
+- hlavičku,
+- ovládanie vhodné pre dotyk,
+- formuláre,
+- tlačidlá,
+- chybové a informačné správy,
+- farebnú konzistenciu činností,
+- desktopové breakpointy,
+- použiteľnosť časovej osi na rôznych šírkach displeja.
+
+Nepoužívať CSS framework.
+
+### Výsledok
+
+Všetky doteraz implementované obrazovky pôsobia ako jedna konzistentná aplikácia a sú pohodlne použiteľné na mobile aj desktope.
+
+---
+
+## Krok 15 – PWA
+
+Doplniť základné PWA časti:
+
+- `manifest.json`,
+- názov aplikácie,
+- theme/background farby,
+- ikony 192 × 192 a 512 × 512,
+- `service-worker.js`,
+- registráciu service workera,
+- potrebné meta tagy.
+
+Cieľom je umožniť inštaláciu aplikácie na zariadenie.
+
+Offline funkcionalitu aplikačných dát neimplementovať. Service worker nemá vytvárať dojem, že zápis udalostí funguje offline, ak to aplikácia nevie bezpečne synchronizovať.
+
+### Výsledok
+
+TimeLog je instalovateľná PWA určená na online používanie.
+
+---
+
+## Krok 16 – Bezpečnosť, validácia a odolnosť
+
+Prejsť aplikáciu ako celok a doplniť bezpečnostné a validačné opatrenia.
+
+Skontrolovať najmä:
+
+- autentifikáciu každej privátnej akcie,
+- session security,
+- CSRF ochranu pre meniace operácie,
+- escapovanie HTML výstupu proti XSS,
+- validáciu dátumu a času,
+- validáciu ID činnosti,
+- validáciu farby,
+- validáciu loginov,
+- ochranu proti path traversal,
+- bezpečné chyby bez úniku interných ciest a citlivých údajov,
+- neprístupnosť `data/`, `src/`, `docs/` a `var/` z webu,
+- konzistenciu JSON dát pri súbežnom zápise.
+
+### Výsledok
+
+Aplikácia je pripravená na bezpečné nasadenie na vlastný HTTPS server.
+
+---
+
+## Krok 17 – Integračné testovanie kompletnej prvej verzie
+
+Prejsť hlavné používateľské scenáre od začiatku do konca.
+
+Overiť minimálne:
+
+1. prihlásenie,
+2. vytvorenie a úpravu činnosti,
+3. zaznamenanie niekoľkých činností počas dňa,
+4. opravu nesprávneho času,
+5. spätné doplnenie udalosti,
+6. vymazanie udalosti,
+7. prechod činnosti cez polnoc,
+8. dennú časovú os,
+9. denný sumár,
+10. týždenný prehľad,
+11. týždenný sumár,
+12. správu loginov,
+13. použitie na mobilnej šírke,
+14. použitie na desktope,
+15. inštalovateľnosť PWA.
+
+Opraviť zistené regresie a hraničné prípady bez pridávania funkcionality mimo špecifikácie prvej verzie.
+
+### Výsledok
+
+Existuje funkčná a overená prvá verzia TimeLog zodpovedajúca `docs/specification.txt`.
+
+---
+
+## Krok 18 – Príprava produkčného nasadenia
+
+Pripraviť aplikáciu na nasadenie na vlastnú subdoménu.
+
+Zdokumentovať alebo pripraviť:
+
+- nastavenie webrootu na `public/`,
+- požadovanú verziu PHP,
+- práva na zápis do `data/` a potrebných častí `var/`,
+- vytvorenie prvého používateľa,
+- HTTPS,
+- produkčné nastavenie session,
+- zálohovanie JSON dát,
+- kontrolu, že neverejné adresáre nie sú dostupné cez HTTP.
+
+### Výsledok
+
+Aplikáciu je možné reprodukovateľne nasadiť na produkčný server a začať používať.
+
+---
+
+# Poradie ďalšieho rozpracovania
+
+Každý vyššie uvedený krok sa môže neskôr zmeniť na samostatný implementačný prompt.
+
+Taký prompt by mal vždy obsahovať:
+
+- číslo a názov kroku,
+- relevantnú časť `docs/specification.txt`,
+- aktuálny stav repozitára,
+- presný rozsah implementácie,
+- čo sa v danom kroku ešte nemá implementovať,
+- požadované testy alebo spôsob overenia,
+- požiadavku zachovať kompatibilitu s už implementovanými krokmi.
+
+Pri rozpracovaní promptov je vhodné vždy vychádzať aj z aktuálneho obsahu repozitára, nie iba z tohto plánu, pretože implementácia predchádzajúcich krokov môže spresniť technické detaily ďalšieho postupu.