TPsoft.org/WebWizard
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
WebWizard/docs/steps.md
igor 0f791c3a90 added steps for implementation
2026-06-12 11:07:06 +02:00

16 KiB
Raw Permalink Blame History

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/<project_id>.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/<project_id>/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 <main>.

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 <iframe> (prípadne nový tab). Vytvorenie endpointu pre export (exportWebsite), ktorý zbalí vygenerované zložky assets/, messages/, HTML a PHP skripty z príslušného exports/<project_id>/ do .zip archívu (bez akýchkoľvek .json konfiguračných/AI pracovných metadát!). Súbory a moduly:

  • public/js/wizard.js (časť kroku 7 a 8)
  • public/ajax.php Závislosti: Krok 18. DoD: Používateľ si prezerá vyrenderovaný HTML web a po stlačení tlačidla sa mu na stiahnutie odošle ZIP súbor.

Krok 20: Kvalitatívne Validácie a Error Handling Fixes

Cieľ: Komplexné otestovanie MVP proti obmedzeniam architecture.md. Popis implementácie: Revízia generovaného webu cez Linter/Validator nástroje. Zabezpečenie fungovania úplne bez Build-kroku, bez JavaScript runtime závislostí a bez chýb v prehliadači (Vanilla, lokálne obrázky). Prečistenie zbytočného logovania. Validácia, že systém odolá aspoň základným formám vloženia nevyhovujúcich dát (nedostatočné heslá, HTML inject). Súbory a moduly:

  • Plošný re-check existujúceho kódu. Závislosti: Všetky predošlé. DoD: MVP nevracia PHP error, nevyžaduje npm, vygeneruje striktne Vanilla verziu a beží na čistom PHP 8.2 s file systémom.

Otvorené otázky a poznámky

  • Asynchrónny generátor LLMpool.php: Potrebuje MVP dedikovaný daemon proces pre konzumáciu, alebo sa AI proces zavolá synchronne/na pozadí z requestu, keďže sa neočakáva vysoká záťaž vo fáze testovania MVP?
  • Ochrana formulárov na exportoch: Exportované maily musia obsahovať robustný Anti-Spam (hoci by len jednoduchý honeypot/Rate-limiting na session), toto by sa mohlo špecifikovať pre produkčný beh emailer.php.
  • Verzia textu GDPR: Je definované, že consent_text_version sa eviduje; mechanizmus pre aktualizáciu textov pri už hotovom webe mimo MVP scope zatiaľ absentuje, no v dátovom modeli to je zohľadnené.