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