TimeLog/docs/steps.md

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.