489 lines
13 KiB
Markdown
489 lines
13 KiB
Markdown
# 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.
|