diff --git a/docs/index.html b/docs/index.html index da37390..0e47fdf 100644 --- a/docs/index.html +++ b/docs/index.html @@ -80,6 +80,10 @@ mvp.md

Hlavný zdroj pravdy pre MVP. Zhrnutie cieľov, rozsahu, technológií a bezpečnosti.

+
  • + steps.md +

    Plán implementácie MVP. Kompletný zoznam očíslovaných krokov pre postupnú realizáciu celého projektu.

    +
    • diff --git a/docs/steps.md b/docs/steps.md new file mode 100644 index 0000000..d35ba27 --- /dev/null +++ b/docs/steps.md @@ -0,0 +1,271 @@ +# WebWizard - Plán implementácie MVP + +Tento dokument definuje kompletný implementačný plán pre MVP vo forme sekvenčných krokov. Tieto kroky sú navrhnuté tak, aby boli samostatne realizovateľné AI agentom, pričom každý zohľadňuje pravidlá z `architecture.md`, používateľský tok z `wizard.md` a ciele z `mvp.md`. + +--- + +## Krok 1: Inicializácia projektu a základná štruktúra + +**Cieľ:** Vytvoriť základnú adresárovú štruktúru a nastavenia bezpečnosti (napr. neprístupný `data/` priečinok). +**Popis implementácie:** +Vytvorenie adresárov `data/` (a jeho podadresárov `users`, `projects`, `consent`, `llm`, `admin`), `exports/`, `src/` a `public/`. Príprava `composer.json` na autoloading (PSR-4) pre priečinok `src/` (žiadne externé knižnice sa do MVP nepridávajú, iba vlastné triedy). Nastavenie ochrany v `.htaccess` na zamedzenie prístupu k ukladaciemu priečinku `data/` cez webový prehliadač. +**Súbory a moduly:** +* `composer.json` +* `.htaccess` (alebo server konfigurácia) +* Adresárová štruktúra: `data/`, `exports/`, `src/`, `public/` +**Závislosti:** Žiadne. +**Definition of Done (DoD):** Adresárová štruktúra existuje, funguje PSR-4 autoloading z `src/` a priamy prístup do `/data/` vracia 403 Forbidden (alebo podobnú blokáciu). + +--- + +## Krok 2: Core Data Services (Úložisko) + +**Cieľ:** Implementovať triedu pre bezpečné čítanie a zápis JSON súborov vo file-based úložisku. +**Popis implementácie:** +Vytvorenie služby `src/Services/FileStorage.php`, ktorá bude riešiť ukladanie a načítavanie dát pre používateľov, projekty, AI frontu a metadáta. Táto služba musí zvládať zapisovanie/čítanie polí/objektov a konverziu do JSON. Musí byť ošetrená voči "path traversal" chybám a pracovať výlučne v priečinku `data/`. +**Súbory a moduly:** +* `src/Services/FileStorage.php` +**Závislosti:** Krok 1. +**DoD:** Objekt `FileStorage` dokáže úspešne uložiť asociatívne pole ako JSON do `data/users/` a spätne ho z neho bezpečne načítať bez warningov. + +--- + +## Krok 3: API vrstva a Error Handling + +**Cieľ:** Pripraviť vstupný bod pre AJAX požiadavky a jednotné riadenie chýb. +**Popis implementácie:** +Vytvorenie endpointu `public/ajax.php`. Skript bude spracovávať POST požiadavky vo formáte JSON, verifikovať hlavičku `X-User-ID` a delegovať akcie (switch). Zabezpečenie jednotného formátu odpovedí (polia `success`, `data`, alebo `error`). Implementácia globálneho záchytu výnimiek a logovania chýb. +**Súbory a moduly:** +* `public/ajax.php` +**Závislosti:** Krok 2. +**DoD:** API korektne odpovedá na neznámu akciu s chybou v stanovenom JSON formáte. Ošetrené zachytávanie PHP warningov. + +--- + +## Krok 4: Správa používateľov a projektov (Session) + +**Cieľ:** Implementovať správu používateľskej relácie (identifikátor) a vytváranie projektov. +**Popis implementácie:** +Implementácia akcií `initSession`, `createProject`, `listProjects`, a `getProjectStatus` v `ajax.php`. Načítanie užívateľa pomocou ID. Inicializácia základnej schémy prázdneho projektu s identifikátorom, stavom `draft` a štruktúrou `wizard_data`. Integrácia so službou `FileStorage`. +**Súbory a moduly:** +* `public/ajax.php` +* `src/Actions/ProjectActions.php` (dobrovoľné vyčlenenie biznis logiky projektov) +**Závislosti:** Krok 3. +**DoD:** Z GET/POST requestu vie frontend vyžiadať `initSession` a získa ID, s ktorým následne úspešne vytvorí projekt (viditeľný ako JSON na disku). + +--- + +## Krok 5: Služba pre GDPR súhlas + +**Cieľ:** Vytvoriť auditovateľnú evidenciu GDPR súhlasu podľa `architecture.md`. +**Popis implementácie:** +Vytvorenie `src/Services/ConsentService.php` a pridanie API akcie `saveConsent`. Služba vytvorí JSON záznam v `data/consent/` so stanovenou schémou (verzia textu, UTC čas, text, IDs). Validácia, ktorá zablokuje uloženie kľúčových dát vo wizadre, kým tento záznam pre daný projekt neexistuje. +**Súbory a moduly:** +* `src/Services/ConsentService.php` +* `public/ajax.php` +**Závislosti:** Krok 4. +**DoD:** API požiadavka na `saveConsent` vygeneruje súbor v `data/consent/.json` s presným textom a metadátami súhlasu. + +--- + +## Krok 6: Kostra Wizardu (Frontend UI) + +**Cieľ:** Pripraviť Vanilla JS klientskú aplikáciu pre wizard a navigáciu medzi krokmi. +**Popis implementácie:** +Vytvorenie `public/index.html` s potrebnou DOM štruktúrou pre zobrazenie jednotlivých krokov. Pripojenie scriptov (`public/js/wizard.js`) a základného CSS štýlovania. Implementácia checku z localStorage na `ww_user_id`, volanie `initSession` ak chýba. Implementácia funkcie pre prechod medzi krokmi, zobrazenie/skrytie kontejnerov a ukladanie na server pomocou `saveStep`. +**Súbory a moduly:** +* `public/index.html` +* `public/js/wizard.js` +* `public/css/wizard.css` +**Závislosti:** Krok 4. +**DoD:** Frontent sa úspešne načíta, prihlási užívateľa (vygeneruje mu ID ak ho nemá), a umožní prepínanie krokov s odosielaním mock dát na backend cez `saveStep`. + +--- + +## Krok 7: Wizard - Segmentácia biznisu (Krok 1) + +**Cieľ:** UI a zber dát pre prvotnú segmentáciu. +**Popis implementácie:** +Zobrazenie kategórií z `data/categories.json` na FE. Logika pre výber kategórie (radio karty) a podkategórie. Spracovanie poľa "Iné" pre vlastný typ a jeho prípadné uloženie do `data/admin/pending_categories.json`. Uloženie výberu pod `business_category` do objektu `wizard_data`. +**Súbory a moduly:** +* `public/js/wizard.js` (časť kroku 1) +* `data/categories.json` (mock dát kategórií) +**Závislosti:** Krok 6. +**DoD:** Používateľ vie vybrať segment biznisu a jeho dáta sa v backendovom JSONe projektu správne zmenia. + +--- + +## Krok 8: Wizard - Identita a Kontakt (Krok 2) + +**Cieľ:** Zber firemných a kontaktných informácií spoločne so záväzným odsúhlasením GDPR. +**Popis implementácie:** +Polia pre identitu (povinný názov). Polia pre kontakt (povinný buď email, alebo tel. číslo). Implementácia povinného checkboxu pre súhlas. Frontend nedovolí volať uloženie, pokiaľ checkbox nie je označený, po uložení najprv volá akciu `saveConsent` a až potom `saveStep`. Backend validuje povinné polia a prítomnosť súhlasu. +**Súbory a moduly:** +* `public/js/wizard.js` (časť kroku 2) +* `public/ajax.php` (rozšírenie o validácie `saveStep` pre krok 2) +**Závislosti:** Krok 5, 7. +**DoD:** Dáta sa na backend uložia iba v prípade, že validácie prejdú a bol prijatý GDPR súhlas. + +--- + +## Krok 9: Wizard - Služby a Smart otázky (Krok 3) + +**Cieľ:** Dynamický zber obsahových vstupov v závislosti od segmentu. +**Popis implementácie:** +Rozhranie s možnosťou dynamicky pridávať/odstraňovať položky služieb. Zobrazenie dodatočných check-boxov a inputov (tzv. "Smart answers") v závislosti od uloženej `business_category` z Kroku 1 (napr. otváracie hodiny, donáška). Funkcia "Preskočiť" pre voliteľné polia. +**Súbory a moduly:** +* `public/js/wizard.js` (časť kroku 3) +* Rozšírenie definície z `data/categories.json` +**Závislosti:** Krok 8. +**DoD:** Používateľ úspešne zadá 2 a viac služieb a odošle ich; dáta sú prítomné v projektovom JSONe v sekcii `services.items`. + +--- + +## Krok 10: Wizard - Vizuál a Assety (Krok 4) + +**Cieľ:** Zber grafických vstupov, farieb a nahrávanie obrázkov s validáciou. +**Popis implementácie:** +Výber štýlu a layoutu. Pripravenie endpointu pre asynchrónny file upload loga a obrázkov (`public/ajax.php` -> akcia `uploadAsset`). Základná sanitizácia MIME (povoľuje len JPG, PNG, WEBP, alebo zabezpečené SVG), kontrola obmedzenia veľkosti do rozumného limitu a ochrana voči path traversalu. Ukladanie súborov pod `exports//assets/images/`. Mapovanie alt-textov. +**Súbory a moduly:** +* `public/js/wizard.js` (časť kroku 4) +* `public/ajax.php` +* `src/Services/FileStorage.php` (alebo dedikovaná služba pre upload) +**Závislosti:** Krok 9. +**DoD:** Obrázok sa nahrá asynchrónne na server, validuje sa a v `wizard_data.assets` sa priradí adresa z nahraného umiestnenia s voliteľným alt-textom. + +--- + +## Krok 11: Wizard - Moduly a Formulár (Krok 5) + +**Cieľ:** Výber rozsahu obsahu a nastavenie režimu fungovania kontaktného formulára. +**Popis implementácie:** +Checkboxový výber dostupných sekcií pre web (about, services, gallery, atď.). Možnosť výberu režimu pre kontaktný formulár: SMTP (polia host, port, user, atď.) alebo Lokálny mód (nastavenie hesla na zobrazenie správ a jeho zaheshovanie pred uložením v `wizard_data.modules.contact_form.local_viewer`). +**Súbory a moduly:** +* `public/js/wizard.js` (časť kroku 5) +* `public/ajax.php` (heshovanie hesla) +**Závislosti:** Krok 10. +**DoD:** Používateľ dokáže zvoliť formulár a jeho konfigurácia i prípadný lokálny hesh sú správne uložené v JSONe. + +--- + +## Krok 12: Generovanie fronty úloh (AI Queue) + +**Cieľ:** Pripraviť frontu úloh pre spracovanie obsahu pomocou DAIAPI. +**Popis implementácie:** +Frontend zavolá akciu `generateWebsite`. Backend prepne projekt zo stavu `draft` do stavu `queued` a vytvorí JSON úlohu s `task_id` obsahujúcu kompletné `wizard_data` vo foldri `data/llm/`. Nastavenie počítadla pokusov pre fail handling. +**Súbory a moduly:** +* `public/ajax.php` +* `src/Actions/TaskActions.php` (manažment taskov) +**Závislosti:** Krok 11. +**DoD:** Na disku v `data/llm/` fyzicky vznikne nový súbor obsahujúci úlohu spárovanú s `project_id`. + +--- + +## Krok 13: Architektúra promptov a DAIAPI klient + +**Cieľ:** Implementácia komponentov na dopytovanie lokalného LLM na generovanie štrukturovaných dát. +**Popis implementácie:** +Vytvorenie `src/Services/DAIClient.php` na lokálnu HTTP požiadavku voči DAIAPI. Zadefinovanie `src/Prompts/content_prompt.php` - zloženie promptu na základe hodnôt vo `wizard_data`, tak aby AI vrátilo explicitne `JSON content layer` ako stanovuje `specification2.md`. +**Súbory a moduly:** +* `src/Services/DAIClient.php` +* `src/Prompts/content_prompt.php` +**Závislosti:** Krok 12. +**DoD:** Prompt správne prijíma mock objekt z wizarda a formátuje reťazec vrátane striktného príkazu "No HTML output". DAIClient vie úspešne odoslať request a prečítať payload. + +--- + +## Krok 14: Služba LLMpool a Validácia AI výstupu + +**Cieľ:** Konzumovať LLM frontu na pozadí (alebo sekvenčne) a overovať vrátený formát obsahu. +**Popis implementácie:** +Implementácia skriptu `LLMpool.php`, ktorý vyberie "queued" task z fronty, zamkne ho a posunie prompt na `DAIClient`. Po obdržaní odpovede implementovať striktnú JSON validáciu a overenie, že návrat nevytvára DOM/HTML prvky. Ak prejde, skript zapíše obsah ako `content.generated` pod daným projektom; v opačnom prípade inkrementuje chyby a označí task ako zlyhaný (Retry limit = 3). +**Súbory a moduly:** +* `src/Services/LLMpool.php` +**Závislosti:** Krok 13. +**DoD:** Skript vie načítať task, spracovať ho s klientom, zvalidovať a po úspechu zapísať vygenerovaný obsah do projektu a nastaviť stav projektu na `rendering`. + +--- + +## Krok 15: Rendering Vrstva (Jadro a Baseline šablóna) + +**Cieľ:** Postaviť deterministický systém pre tvorbu HTML kódu zo štruktúrovaných AI dát. +**Popis implementácie:** +Služba `src/Services/Renderer.php`, ktorá spracuje kombináciu `wizard_data` a `content.generated`. Pripraví základnú kostru - HTML5 šablónu (sémantické tagy, jazyk, viewport meta tagy, SEO metadáta načítané z obsahu). Musí vykonávať tvrdé HTML escapovanie pri vkladaní z JSONu. +**Súbory a moduly:** +* `src/Services/Renderer.php` +* `src/Templates/base.php` +**Závislosti:** Krok 14. +**DoD:** Renderer vytvorí súbor `index.html` na správnom mieste exportu, s vyplnenými SEO hlavičkami a prázdnym `
    `. + +--- + +## Krok 16: Rendering Vrstva (Obsahové Sekcie) + +**Cieľ:** Implementácia vykresľovania jednotlivých AI sekcií na webe. +**Popis implementácie:** +Implementácia šablón a generovania pre vybrané moduly v `wizard_data.modules.sections` (Hero blok, Služby, Cenník, Galéria, O nás, FAQ, Testimonials a Kontakt/Pätička). Implementácia fallback hodnôt pre alt-texty a podpora accessibility zaisťujúca logickú hierarchiu nadpisov (len jeden H1). Všetky tagy majú byť semantické (žiadna "div polievka"). +**Súbory a moduly:** +* `src/Templates/sections/*.php` +* `src/Services/Renderer.php` +**Závislosti:** Krok 15. +**DoD:** Vygenerované HTML preukázateľne mapuje údaje z `content.generated` do konkrétnych oddielov a je validné W3C bez rozbitého escapovania. + +--- + +## Krok 17: Rendering Vrstva (CSS Assety) + +**Cieľ:** Transformovať vstupy dizajnu (farby, fonty, styling) do kaskádových štýlov webu. +**Popis implementácie:** +V `Renderer.php` pridať logiku pre zgenerovanie premenných do `:root` selektoru. Vygenerovanie premenných ako farby z `wizard_data.visuals.color_scheme`, vybratie prednastavených web-safe/google fontov (sans/serif) a transformovanie hustoty rozloženia pre spacing/margin premenné. Skopírovať statický CSS skeleton na miesto `site.css`. +**Súbory a moduly:** +* `src/Templates/css/site.css` +* `src/Services/Renderer.php` +**Závislosti:** Krok 16. +**DoD:** HTML po otvorení pripojí a rešpektuje farby/typo a rozloženie vo vygenerovanom exporte. + +--- + +## Krok 18: Kontakt a Formuláre (SMTP & Lokálny mód) + +**Cieľ:** Sprístupniť a plne nakonfigurovať kontaktný formulár vo výstupe podľa režimu. +**Popis implementácie:** +Ak používateľ vybral SMTP - nakonfiguruje premenné, nakopíruje `emailer.php` a naviaže POST formuláru naň. +Ak používateľ vybral Lokálny mód - vytvorí štruktúru `messages/` s potrebnými oprávneniami, do exportu vloží `form-viewer.php` pre prehliadanie správ (chránené heshovaným heslom z `wizard_data`). Ošetrenie proti zneužitiu a path traversalu vo formulárových endpointoch exportovaného webu. +**Súbory a moduly:** +* `src/Templates/emailer.php` +* `src/Templates/form-viewer.php` +* `src/Services/Renderer.php` +**Závislosti:** Krok 17. +**DoD:** Odoslanie kontaktného formulára z exportovanej stránky nezlyhá a zachová sa požadovaným spôsobom. + +--- + +## Krok 19: Preview a Export (Posledné fázy Wizarda) + +**Cieľ:** Zavŕšenie UX cesty možnosťou preview a finálneho exportu. +**Popis implementácie:** +Implementácia kroku 7 vo wizadre – vygenerovaný web z `exports/` sa načíta vo vnútri frontendu napr. do `