Add implementation steps
This commit is contained in:
+488
@@ -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.
|
||||||
Reference in New Issue
Block a user