From a0a1365d48701d4eb35dceb7e5c1ba4cfdc7c97d Mon Sep 17 00:00:00 2001 From: igor Date: Thu, 11 Jun 2026 19:10:52 +0200 Subject: [PATCH] merged data info and created one mvp.md --- docs/architecture.md | 540 ++++++++++++++++++++++++++++++++--------- docs/mvp.md | 275 +++++++++++++++++++++ docs/specification.md | 362 ++++++++++++--------------- docs/specification2.md | 290 +++++++++++++++------- docs/wizard.md | 438 +++++++++++++++++++++++---------- 5 files changed, 1364 insertions(+), 541 deletions(-) create mode 100644 docs/mvp.md diff --git a/docs/architecture.md b/docs/architecture.md index d6d8566..2d1e1a4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,128 +1,322 @@ -# WebWizard - MVP Architektúra +# WebWizard - MVP Architektura -Tento dokument definuje technickú architektúru pre prvú verziu (MVP) projektu WebWizard. Cieľom je maximálna jednoduchosť, rýchlosť vývoja a nulová závislosť na komplexných infraštruktúrach (databáza, cloud služby). +Tento dokument definuje technicku architekturu MVP. Zjednocuje projekt na jednoduchu stackovu liniu: PHP 8.2, JSON subory, Vanilla JavaScript a lokalne DAIAPI. --- -## 1. Celková architektúra systému +## 1. Principy MVP -Systém funguje na princípe **Single-Page Application (SPA)** komunikujúcej s **tenkým Backendom** cez AJAX. +* **AI website concierge, nie builder:** pouzivatel odpoveda na otazky, system pripravi export. +* **File-based persistence:** vsetky data su JSON subory. +* **AI negeneruje HTML:** AI vytvara iba strukturovany content JSON. +* **Renderer generuje HTML:** PHP rendering layer vytvara exportovatelny web z JSON dat. +* **Bez frameworkov:** ziadny backend ani frontend framework, ziadny build proces. +* **Bez domen a hostingu v MVP:** vystupom je exportovatelny webovy priecinok. + +--- + +## 2. Celkova architektura ```ascii -[ Používateľ (Prehliadač) ] - | - | AJAX (POST /ajax.php) - v -[ PHP Backend (ajax.php) ] <----> [ Súborový systém (JSON & HTML) ] - | - | Lokálne API Call (HTTP) - v -[ AI Engine (DAIAPI) ] +[ Browser / Wizard UI ] + | + | AJAX POST /ajax.php + v +[ PHP API Layer ] + | + +--> [ JSON Storage: users, projects, consent, categories ] + | + +--> [ AI Queue: data/llm/*.json ] + | + v + [ LLMpool.php ] + | + v + [ Local DAIAPI ] + | + v + [ Content Layer: generated JSON ] + | + v + [ Rendering Layer: PHP renderer ] + | + v + [ Exported Website: HTML/CSS/assets/PHP form scripts ] ``` -### Princípy: -* **Stateless Backend:** PHP neudržiava session v pamäti, identita používateľa sa posiela v každej požiadavke. -* **File-based Persistence:** Všetky dáta sú v JSON súboroch. -* **Local AI Integration:** Systém využíva lokálnu inštanciu DAIAPI, čo znižuje latenciu a náklady. -* **Decoupled Frontend:** Frontend je čisté HTML/JS, ktoré možno hostovať kdekoľvek. +--- + +## 3. Pouzite technologie + +MVP pouziva: + +* PHP 8.2, +* JSON subory, +* Composer volitelne, +* HTML, +* CSS, +* Vanilla JavaScript, +* lokalne DAIAPI. + +MVP nepouziva: + +* databazu, +* backend framework, +* React, Vue, Angular, +* TypeScript, +* build proces, +* cloud storage ako povinnu zavislost. --- -## 2. Použité technológie - -* **Backend:** PHP 8.2+ (bez frameworku). -* **Frontend:** Vanilla JavaScript (ES6+), HTML5, Vanilla CSS. -* **AI:** DAIAPI (lokálne HTTP rozhranie pre LLM). -* **Server:** Apache/Nginx s podporou `.htaccess` (na ochranu dátových priečinkov). -* **Balíčkovací manažér:** Composer (voliteľne pre pomocné knižnice). - ---- - -## 3. Adresárová štruktúra +## 4. Adresarova struktura ```text / -├── data/ # NEPRÍSTUPNÉ Z WEBU (.htaccess deny all) -│ ├── users/ # .json -│ ├── projects/ # .json -│ └── llm/ # Fronta úloh pre AI (prikazy.json) -├── sites/ # PRÍSTUPNÉ Z WEBU (Vygenerované weby) -│ └── a8f7c3d1/ # Konkrétny vygenerovaný web -│ ├── index.html -│ ├── assets/ -│ ├── images/ -│ └── config.json # Kópia konfigurácie pre daný export -├── src/ # PHP Logika -│ ├── Actions/ # Triedy pre jednotlivé AJAX akcie -│ ├── Services/ # AI Engine (LLMpool.php), FileStorage, Renderer -│ ├── Prompts/ # Externé prompty (.txt, .md) -│ └── Utils/ # Helpery -├── public/ # Root webservera -│ ├── index.html # Hlavná aplikácia (Wizard) -│ ├── ajax.php # Jediný vstupný bod pre API -│ ├── css/ -│ └── js/ -├── vendor/ # Composer závislosti -└── composer.json ++-- data/ # Neverejne data +| +-- users/ # .json +| +-- projects/ # .json +| +-- consent/ # .json alebo .json +| +-- categories.json # Definicia kategorii a smart otazok +| +-- admin/ +| | +-- pending_categories.json +| +-- llm/ # Fronta AI uloh ++-- exports/ # Exportovane weby +| +-- / +| +-- index.html +| +-- config.json +| +-- assets/ +| | +-- site.css +| | +-- site.js +| | +-- images/ +| +-- messages/ # Iba lokalny formularovy mod +| +-- emailer.php # Iba SMTP mod +| +-- form-viewer.php # Iba lokalny formularovy mod ++-- src/ +| +-- Actions/ +| +-- Services/ +| | +-- FileStorage.php +| | +-- DAIClient.php +| | +-- Renderer.php +| | +-- ConsentService.php +| +-- Prompts/ +| +-- Templates/ +| +-- Utils/ ++-- public/ +| +-- index.html +| +-- ajax.php +| +-- css/ +| +-- js/ ++-- vendor/ ++-- composer.json ``` +`data/` musi byt neverejne. Ak je webserver root nad projektom, priecinok `data/` musi byt chraneny pravidlom `.htaccess` alebo konfiguraciou servera. + --- -## 4. Štruktúra dát (JSON) +## 5. Datove subory + +### Pouzivatel + +`data/users/.json` -### Používateľ (`data/users/.json`) ```json { "user_id": "u_9b12ef44", "created_at": "2026-06-11T10:00:00Z", - "projects": ["p_a8f7c3d1", "p_b2c3d4e5"] + "projects": ["p_a8f7c3d1"] } ``` -### Projekt (`data/projects/.json`) +### Projekt + +`data/projects/.json` + ```json { "project_id": "p_a8f7c3d1", "user_id": "u_9b12ef44", - "status": "in_progress", - "current_step": 3, - "wizard_data": { - "business_type": "restaurant", - "name": "Pizza Marco", - "city": "Košice" + "status": "draft", + "current_step": 2, + "wizard_data": {}, + "content": { + "generated": null, + "generated_at": null }, - "generated_at": null, - "site_path": "/sites/a8f7c3d1/" + "export": { + "path": "exports/p_a8f7c3d1", + "generated_at": null + }, + "created_at": "2026-06-11T10:00:00Z", + "updated_at": "2026-06-11T10:05:00Z" } ``` ---- +### Stavy projektu -## 5. Identifikácia používateľa - -**Riešenie: LocalStorage + HTTP Header.** - -1. Pri prvej návšteve JS skontroluje `localStorage.getItem('ww_user_id')`. -2. Ak neexistuje, pošle požiadavku na `action=initSession`. -3. Backend vygeneruje unikátny hash (napr. `bin2hex(random_bytes(8))`) a vráti ho. -4. JS ho uloží do `localStorage`. -5. **V každej ďalšej AJAX požiadavke** sa tento ID posiela v HTTP hlavičke `X-User-ID`. - -**Zdôvodnenie:** -* Čistejšie API: Payload obsahuje len dáta súvisiace s akciou, identita je v metadátach (hlavičkách). -* Jednoduchšia autorizácia na úrovni backendu ešte pred parsovaním JSON tela. -* LocalStorage je pre SPA prirodzenejší a nevyžaduje riešenie CSRF tokenov v takej miere ako automaticky posielané cookies. +* `draft` - wizard je rozpracovany, +* `queued` - AI uloha je vo fronte, +* `generating` - DAIAPI spracovava ulohu, +* `content_ready` - AI JSON je ulozeny, +* `rendering` - renderer vytvara export, +* `export_ready` - export je pripraveny, +* `failed` - generovanie alebo render zlyhalo. --- -## 6. AJAX Komunikácia +## 6. Wizard Data Schema -Všetky požiadavky smerujú na `public/ajax.php`. +`wizard_data` je kanonicky vstupny model pre AI aj renderer. -### Formát požiadavky: -`POST /ajax.php` -`Content-Type: application/json` -`X-User-ID: u_9b12ef44` +```json +{ + "identity": { + "business_name": "Pizza Marco", + "tagline": "Poctiva pizza v Kosiciach", + "description": "Rodinna pizzeria zamerana na donasku a denne menu" + }, + "contact": { + "email": "info@pizzamarco.sk", + "phone": "+421 900 000 000", + "address": "Hlavna 1, Kosice", + "city": "Kosice", + "region": "Kosicky kraj", + "socials": { + "facebook": "https://facebook.com/pizzamarco", + "instagram": "https://instagram.com/pizzamarco" + } + }, + "services": { + "items": [ + { + "name": "Donaska pizze", + "description": "Rozvoz po Kosiciach", + "price_from": "7 EUR" + } + ], + "pricing_note": "Ceny su orientacne." + }, + "visuals": { + "style": "modern", + "color_scheme": { + "primary": "#C62828", + "secondary": "#F8F1E7", + "accent": "#2E7D32", + "background": "#FFFFFF", + "text": "#1A1A1A" + }, + "font_style": "sans", + "layout_density": "comfortable" + }, + "modules": { + "pages": ["home"], + "sections": ["hero", "about", "services", "pricing", "gallery", "faq", "contact"], + "contact_form": { + "enabled": true, + "mode": "local", + "smtp": null, + "local_viewer": { + "password_hash": "$2y$..." + } + } + }, + "assets": { + "logo": { + "uploaded": true, + "path": "assets/images/logo.png", + "alt": "Logo Pizza Marco" + }, + "images": [ + { + "path": "assets/images/interior.jpg", + "alt": "Interier pizzerie" + } + ], + "image_source": "uploaded" + }, + "language": { + "primary": "sk", + "additional": [], + "tone": "friendly" + }, + "business_category": { + "group": "gastro", + "subcategory": "restaurant", + "custom_description": null + }, + "smart_answers": { + "delivery": true, + "daily_menu": true, + "reservations": false, + "opening_hours": "Po-Pia 10:00-21:00" + } +} +``` + +### Vyznam sekcii + +* `identity` - nazov, slogan a popis firmy; AI nesmie tieto fakty menit. +* `contact` - kontaktne udaje pouzite v hlavicke, pate a formulari. +* `services` - zoznam sluzieb, produktov alebo balikov. +* `visuals` - dizajnovy smer, farby, typografia a hustota layoutu. +* `modules` - zoznam sekcii a konfiguracia funkcnych modulov. +* `assets` - logo, obrazky, alt texty a zdroj obrazkov. +* `language` - primarny jazyk a ton komunikacie. +* `business_category` - kategoria, podkategoria alebo vlastny typ podnikania. +* `smart_answers` - odpovede na dynamicke otazky podla segmentu. + +--- + +## 7. GDPR suhlas + +V kroku wizardu s identitou a kontaktom je povinny checkbox: + +> Suhlasim so spracovanim zadanych udajov za ucelom vytvorenia webovej stranky. + +Bez zaskrtnutia backend odmietne `saveStep` pre krok identity aj `generateWebsite`. + +Suhlas sa uklada do `data/consent/.json`: + +```json +{ + "project_id": "p_a8f7c3d1", + "user_id": "u_9b12ef44", + "consent_text_version": "webwizard-mvp-2026-06-11", + "consent_text": "Suhlasim so spracovanim zadanych udajov za ucelom vytvorenia webovej stranky.", + "accepted": true, + "accepted_at": "2026-06-11T10:05:00Z" +} +``` + +Backend eviduje cas suhlasu v UTC a verziu textu suhlasu. Ak sa text suhlasu zmeni, verzia sa zvysi a pouzivatel musi potvrdit novu verziu. + +--- + +## 8. Identifikacia pouzivatela + +MVP pouziva `localStorage` a HTTP hlavicku. + +1. Frontend skontroluje `localStorage.getItem('ww_user_id')`. +2. Ak hodnota chyba, zavola `initSession`. +3. Backend vytvori `user_id`, ulozi `data/users/.json` a vrati ho. +4. Frontend posiela `X-User-ID` v kazdej AJAX poziadavke. + +`user_id` nie je plnohodnotna autentifikacia. Je to MVP identifikator rozpracovanych projektov v jednom prehliadaci. + +--- + +## 9. AJAX API + +Vsetky poziadavky smeruju na: + +```text +POST /ajax.php +Content-Type: application/json +X-User-ID: u_9b12ef44 +``` + +Priklad poziadavky: ```json { @@ -130,58 +324,162 @@ Všetky požiadavky smerujú na `public/ajax.php`. "project_id": "p_a8f7c3d1", "payload": { "step": 2, - "data": { "name": "Pizza Marco" } + "data": {} } } ``` -### Zoznam akcií: -* `initSession`: Vytvorí nového používateľa. -* `listProjects`: Vráti zoznam projektov používateľa. -* `createProject`: Inicializuje nový projekt. -* `saveStep`: Uloží rozpracované dáta z wizardu. -* `generateWebsite`: Spustí AI generovanie a vytvorí súbory. -* `getProjectStatus`: Pre polling počas generovania. +### Jednotny format odpovedi + +Uspech: + +```json +{ + "success": true, + "data": {} +} +``` + +Chyba: + +```json +{ + "success": false, + "error": { + "code": "ERROR_CODE", + "message": "Human readable message" + } +} +``` + +Ine formaty odpovedi nie su povolene. + +### Akcie + +* `initSession` - vytvori pouzivatela. +* `listProjects` - vrati projekty pouzivatela. +* `createProject` - vytvori projekt v stave `draft`. +* `saveStep` - ulozi cast `wizard_data` a validuje ju. +* `saveConsent` - ulozi GDPR suhlas s verziou textu. +* `generateWebsite` - zaradi AI ulohu do fronty. +* `getProjectStatus` - vrati stav projektu, chybu a cestu exportu. +* `renderWebsite` - pregeneruje HTML z uz existujuceho content JSON. +* `exportWebsite` - vrati informacie o exportnom priecinku alebo archive. --- -## 7. Generovanie a publikovanie (Asynchrónny proces) +## 10. AI workflow -Kvôli eliminácii timeoutov a stabilite generovania využíva systém **LLM Pool**. +`generateWebsite` vytvori ulohu: -### Workflow: -1. **Vytvorenie úlohy:** AJAX akcia `generateWebsite` nezavolá AI hneď. Zapíše JSON súbor do `/data/llm/.json`, ktorý obsahuje vstupné dáta z wizardu a cieľové cesty. -2. **Spracovanie (LLMpool.php):** - * Skript spúšťaný cez **Cron** (napr. každú minútu) prechádza zložku `/data/llm/`. - * Pre každú úlohu načíta príslušný **Prompt** zo zložky `/src/Prompts/`. - * Nahradí premenné v prompte (napr. `[BUSINESS_TYPE]`) reálnymi dátami. - * Pošle požiadavku do DAIAPI. -3. **Dynamické generovanie:** - * Systém nepoužíva fixné HTML šablóny. - * AI inštruujeme, aby vygenerovalo kompletný kód (HTML/CSS) na mieru. -4. **Zápis a Cleanup:** - * Po úspešnom vygenerovaní skript vytvorí súbory v `/sites//`. - * Až po úspešnom zápise sa úloha z `/data/llm/` odstráni. - * **Retry mechanizmus:** Ak DAIAPI zlyhá, súbor s úlohou ostáva v zložke a skript sa ho pokúsi spracovať v ďalšom behu. +```json +{ + "task_id": "t_123", + "project_id": "p_a8f7c3d1", + "status": "queued", + "attempt_count": 0, + "max_attempts": 3, + "created_at": "2026-06-11T10:10:00Z", + "wizard_data": {} +} +``` + +`LLMpool.php`: + +1. zamkne ulohu, +2. nastavi projekt na `generating`, +3. nacita prompt zo `src/Prompts/`, +4. posle poziadavku do DAIAPI, +5. validuje, ze odpoved je JSON bez HTML, +6. ulozi `content.generated`, +7. spusti renderer, +8. nastavi stav `export_ready` alebo `failed`. + +Retry pravidla: + +* maximalne 3 pokusy, +* `attempt_count` sa zvysuje pri kazdom pokuse, +* posledna chyba sa ulozi do projektu, +* po prekroceni limitu sa stav nastavi na `failed`. --- -## 8. Správa dát a Limity (Storage Management) +## 11. Kontaktny formular -1. **Ochrana dát:** `.htaccess` v priečinku `/data/` s obsahom `Deny from all`. -2. **Uploady:** - * Limit na veľkosť súboru (napr. max 2MB pre logo). - * Kontrola povolených prípon (jpg, png, svg) a overenie MIME typu na strane PHP. -3. **Storage Cleanup:** - * Ak celkový objem dát v `/sites/` presiahne stanovenú kvótu, systém automaticky premaže najstaršie projekty (FIFO - First In, First Out). -4. **Sanitizácia:** PHP `htmlspecialchars()` pri renderovaní, ak je to potrebné, a validácia vstupov proti Path Traversal. +### SMTP mod +Pouzivatel vyplni: + +* SMTP host, +* port, +* username, +* password, +* encryption, +* recipient email. + +Export obsahuje `emailer.php`, ktory odosiela spravy cez SMTP. + +### Lokalny mod + +Ak SMTP nie je nastaveny, formular uklada spravy do: + +```text +messages/YYYY-MM-DD-HHMMSS.json +``` + +Export obsahuje `form-viewer.php`: + +* prihlasenie heslom, +* PHP session, +* logout, +* zoznam sprav, +* detail spravy. --- -## 9. Budúce rozširovanie +## 12. Website Quality Requirements -* **Databáza:** Trieda `FileStorageService` sa nahradí `DatabaseStorageService` implementujúcou rovnaké rozhranie. -* **Vlastné domény:** Webserver sa nakonfiguruje tak, aby doména smerovala do konkrétneho `/sites//` priečinka. Relatívne URL toto umožňujú bez zmeny kódu. -* **Editor:** Pridá sa nová AJAX akcia `updateContent`, ktorá prepíše konkrétne časti v `index.html` alebo v `config.json` a znova vyrenderuje stránku. -* **Auth:** Pridá sa tabuľka (alebo JSON) `credentials`, ktorá prepojí `user_id` s emailom a heslom. +Kazdy export musi splnat: + +* mobile responsive design, +* zakladne SEO meta tagy, +* OpenGraph meta tagy, +* alt texty pre obrazky, +* minimalne accessibility poziadavky, +* validny HTML, +* validny CSS, +* bez JavaScript chyb, +* ziadne externe zavislosti okrem explicitne povolenych, +* relativne URL, +* fungovanie bez build procesu. + +Renderer nesmie zapisovat absolutne URL zavisle od konkretnej domeny. + +--- + +## 13. Bezpecnostne minimum + +* validacia vsetkych vstupov, +* escapovanie hodnot pri renderovani HTML, +* ochrana proti path traversal, +* upload limit pre logo a obrazky, +* kontrola pripony aj MIME typu, +* zakaz spustitelnych uploadov, +* limit velkosti AI vstupu, +* rate limit na AJAX akcie podla `user_id`, +* `data/` nepristupne z webu, +* formularove skripty nesmu citat subory mimo svoj exportny priecinok. + +--- + +## 14. Buduce rozsirenia mimo MVP + +* prihlasovanie emailom a heslom, +* databazove ulozisko, +* vlastne domeny, +* DNS a SSL, +* automaticke nasadenie na hosting, +* drag-and-drop editor, +* viacjazycnost jednym klikom, +* booking integracie, +* AI generovanie obrazkov. diff --git a/docs/mvp.md b/docs/mvp.md new file mode 100644 index 0000000..9b056a5 --- /dev/null +++ b/docs/mvp.md @@ -0,0 +1,275 @@ +# WebWizard - MVP + +Tento dokument je hlavny zdroj pravdy pre MVP. Detailnejsie technicke pravidla su v `architecture.md`; detail wizardu je vo `wizard.md`. + +--- + +## 1. Ciel produktu + +WebWizard je AI website concierge. Pouzivatel vyplni kratky wizard a system mu vytvori exportovatelny staticky web. + +MVP sa sustredi na rychle vytvorenie kvalitneho prveho webu bez toho, aby pouzivatel musel rozumiet dizajnu, HTML alebo hostingu. + +--- + +## 2. MVP rozsah + +MVP obsahuje: + +* wizard na zber dat, +* ulozenie projektu do JSON suborov, +* AI generovanie strukturovaneho JSON obsahu, +* PHP renderer, ktory z JSON dat vytvori HTML/CSS, +* preview, +* export webu, +* kontaktny formular v SMTP alebo lokalnom mode, +* GDPR suhlas pri zadani kontaktov. + +MVP neobsahuje: + +* domenu, +* DNS, +* SSL, +* automaticke nasadenie, +* databazu, +* drag-and-drop editor, +* frontend alebo backend frameworky. + +--- + +## 3. Technologie + +Pouzite technologie: + +* PHP 8.2, +* JSON subory, +* Composer volitelne, +* HTML, +* CSS, +* Vanilla JavaScript, +* lokalne DAIAPI. + +Nepouzivaju sa: + +* databaza, +* React, Vue, Angular, +* TypeScript, +* Node/FastAPI backend, +* Redis alebo S3 ako MVP zavislost. + +--- + +## 4. Architektura + +System ma dve hlavne generovacie vrstvy: + +### Content layer + +AI generuje iba strukturovane JSON data: + +* nazov firmy, +* slogan, +* sluzby, +* text O nas, +* FAQ, +* kontakty, +* benefity, +* referencie, +* SEO metadata, +* alt texty. + +### Rendering layer + +PHP renderer vytvara HTML/CSS z JSON dat. + +Vyhody: + +* zmena sablony nevymaze obsah, +* HTML je mozne opakovane pregenerovat, +* pouzivatel nepride o data, +* buduci editor moze upravovat obsah bez prepisovania HTML. + +--- + +## 5. Wizard + +Wizard ma tieto kroky: + +1. Segmentacia biznisu. +2. Identita, kontakt a GDPR suhlas. +3. Sluzby a smart otazky. +4. Vizualny styl a assety. +5. Moduly webu a kontaktny formular. +6. Generovanie JSON obsahu. +7. Preview vyrenderovaneho webu. +8. Export webu. + +Pouzivatel moze preskocit volitelne kroky a nechat rozhodnutie na AI. Povinne su typ podnikania, nazov, kontakt a GDPR suhlas. + +--- + +## 6. Datovy model + +Kanonicky `wizard_data` obsahuje: + +```json +{ + "identity": {}, + "contact": {}, + "services": {}, + "visuals": {}, + "modules": {}, + "assets": {}, + "language": {}, + "business_category": {}, + "smart_answers": {} +} +``` + +Vyznam sekcii: + +* `identity` - nazov firmy, slogan, kratky popis. +* `contact` - email, telefon, adresa, mesto, socialne siete. +* `services` - sluzby, produkty, cennikove poznamky. +* `visuals` - styl, farby, typografia, hustota layoutu. +* `modules` - sekcie webu a konfiguracia formulara. +* `assets` - logo, obrazky, alt texty. +* `language` - primarny jazyk, dalsie jazyky, ton komunikacie. +* `business_category` - oblast podnikania, podkategoria, vlastny popis. +* `smart_answers` - odpovede na dynamicke otazky podla segmentu. + +--- + +## 7. AI workflow + +1. Backend vytvori AI ulohu z `wizard_data`. +2. `LLMpool.php` posle ulohu do lokalneho DAIAPI. +3. DAIAPI vrati JSON content layer. +4. Backend validuje, ze vystup nie je HTML a ma ocakavane polia. +5. Content JSON sa ulozi do projektu. +6. Renderer vytvori export. + +Ak AI vystup nie je validny JSON alebo obsahuje nepovolene HTML ako hlavny vystup, uloha zlyha a moze sa zopakovat podla retry pravidiel. + +--- + +## 8. Publikovanie webu + +MVP nevykonava publikovanie na domenu. + +Vystupom je exportovatelny priecinok: + +```text +exports// + index.html + config.json + assets/ + emailer.php # iba SMTP formular + form-viewer.php # iba lokalny formular + messages/ # iba lokalny formular +``` + +Vsetky URL su relativne a web funguje bez build procesu. + +--- + +## 9. Kontaktny formular + +### SMTP mod + +Pouzivatel zada SMTP host, port, username, password, encryption a recipient email. Export obsahuje `emailer.php`, ktory odosiela spravy. + +### Lokalny mod + +Ak SMTP nie je nastaveny, formular zapisuje spravy do JSON suborov v `messages/`. Export obsahuje `form-viewer.php` s jednoduchym prihlasenim: + +* heslo, +* session, +* logout. + +Heslo sa uklada iba ako hash. + +--- + +## 10. GDPR + +V kroku identita/kontakt je povinny checkbox: + +> Suhlasim so spracovanim zadanych udajov za ucelom vytvorenia webovej stranky. + +Suhlas sa uklada s: + +* `project_id`, +* `user_id`, +* `accepted_at`, +* `consent_text_version`, +* presnym textom suhlasu. + +Bez suhlasu nie je mozne pokracovat ku generovaniu. + +--- + +## 11. Bezpecnostne minimum + +MVP musi obsahovat: + +* validaciu vstupov, +* escapovanie pri renderovani, +* ochranu proti path traversal, +* neverejny `data/` priecinok, +* upload limity, +* kontrolu MIME typu, +* zakaz spustitelnych uploadov, +* rate limit na citlive AJAX akcie, +* formularove skripty obmedzene na vlastny exportny priecinok. + +--- + +## 12. Neimplementovane funkcionality + +MVP neriesi: + +* registraciu domen, +* DNS, +* SSL, +* hosting deployment, +* prihlasovanie emailom a heslom, +* online platby, +* booking system, +* vizualny editor, +* automaticke preklady celeho webu, +* AI generovanie obrazkov. + +--- + +## 13. Buduce rozsirenia + +Po MVP mozu pribudnut: + +* pouzivatelske ucty, +* databazove ulozisko, +* vlastne domeny, +* deployment na hosting, +* editor obsahu, +* viacjazycne weby, +* SEO odporucania, +* booking integracie, +* AI obrazky. + +--- + +## Website Quality Requirements + +Kazdy export musi splnat: + +* mobile responsive design, +* zakladne SEO meta tagy, +* OpenGraph meta tagy, +* alt texty pre obrazky, +* minimalne accessibility poziadavky, +* validny HTML, +* validny CSS, +* bez JavaScript chyb, +* ziadne externe zavislosti okrem explicitne povolenych, +* relativne URL, +* fungovanie bez build procesu. diff --git a/docs/specification.md b/docs/specification.md index 37a15d8..504adf5 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -1,259 +1,213 @@ -> **"Odpovedzte na pár otázok a AI vám vytvorí web."** +# WebWizard - Produktova specifikacia MVP -wizard vytiahne: +WebWizard je **AI website concierge**: pouzivatel odpovie na kratky wizard a system z tychto odpovedi pripravi exportovatelny staticky web. -* názov firmy -* odvetvie -* lokalita -* služby -* komu predávate -* kontakt -* farby -* štýl -* máte logo? -* chcete formulár? -* chcete cenník? -* chcete galériu? -* jazyky? - -výstup bude násobne lepší. +Cielom MVP nie je vytvorit plnohodnotny website builder. Pouzivatel nema rucne presuvat bloky ani ladit pixely. MVP zbiera kvalitne vstupy, vygeneruje obsah, vyrenderuje web a umozni export. --- -## 3. Psychologicky jednoduchšie +## 1. Produktovy ciel -"Vyplniť formulár" je bežná vec. +Pouzivatel bez technickych znalosti ma ziskat prvy pouzitelny web pre firmu alebo projekt. -"Vytvoriť web" je mentálne náročné. +MVP musi vyriesit: + +* zber dolezitych informacii cez wizard, +* AI vytvorenie textoveho obsahu v strukturovanom JSON formate, +* renderovanie statickeho HTML/CSS z JSON dat, +* export webu bez build procesu, +* volitelny kontaktny formular, +* zakladnu ochranu osobnych udajov. + +MVP nesmie riesit: + +* registraciu domen, +* DNS, +* automaticke nasadenie na domenu, +* SSL, +* databazu, +* frameworky, +* React, Vue, Angular ani TypeScript. --- -# Ako by to mohlo vyzerať +## 2. Zakladny tok pouzivatela -## krok 1 — typ biznisu - -Výber: - -* Reštaurácia -* Kaderníctvo -* Autoservis -* Advokát -* Ubytovanie -* Realitka -* IT firma -* Živnostník -* Iné - -Toto je super, lebo môžeš mať predpripravené prompty/template. - -Napr.: - -restaurant prompt ≠ lawyer prompt +1. Pouzivatel otvori wizard. +2. Vyberie typ podnikania a podkategoriu. +3. Zada identitu firmy, kontaktne udaje a potvrdi GDPR suhlas. +4. Vyplni sluzby, smart odpovede, vizualny styl, moduly, jazyk a obrazky. +5. System ulozi odpovede ako `wizard_data`. +6. Backend vytvori ulohu pre DAIAPI. +7. DAIAPI vrati **iba strukturovany JSON obsah**. +8. Rendering layer vytvori HTML/CSS z JSON dat. +9. Pouzivatel uvidi preview a moze pregenerovat obsah alebo exportovat web. --- -## krok 2 — základné info +## 3. Wizard vstupy -Otázky: +Wizard zbiera minimum povinnych udajov a ostatne hodnoty doplna cez smart defaults. -**Ako sa volá vaša firma?** +Povinne vstupy: -**Čomu sa venujete?** +* typ podnikania, +* podkategoria alebo vlastny popis, +* nazov firmy alebo projektu, +* email alebo telefon, +* GDPR suhlas. -**V akom meste pôsobíte?** +Volitelne vstupy: -**Telefón** - -**Email** - -**Adresa** +* slogan, +* adresa, +* mesto/region, +* sluzby, +* cennik, +* otvaracie hodiny, +* benefity, +* referencie, +* socialne siete, +* logo, +* obrazky, +* farebna paleta, +* styl, +* jazyk, +* kontaktny formular. --- -## krok 3 — služby +## 4. AI generovanie obsahu -Checkboxy + vlastné položky +AI nikdy negeneruje priamo HTML, CSS ani JavaScript. -Pre autoservis: - -☑ výmena oleja -☑ pneuservis -☑ geometria -☑ diagnostika -☑ klimatizácia - -AI už vie z toho skladať sekcie. - ---- - -## krok 4 — vzhľad - -"Aký štýl chcete?" - -* Moderný -* Luxusný -* Firemný -* Minimalistický -* Kreatívny -* Technický - -Farby: - -* modrá -* zelená -* tmavá -* svetlá -* podľa loga - ---- - -## krok 5 — obsah - -"Čo má web obsahovať?" - -☑ Úvodná stránka -☑ O nás -☑ Služby -☑ Cenník -☑ Galéria -☑ Kontakt -☑ Formulár -☑ FAQ - ---- - -## krok 6 — obrázky - -"Máte vlastné fotky?" - -* upload - alebo - -"Použiť AI/stock obrázky" - ---- - -## krok 7 — jazyk - -* Slovenčina -* Angličtina -* oba - ---- - -## krok 8 — preview - -AI vygeneruje draft. - -Možnosti: - -* regenerovať design -* regenerovať text -* publikovať - ---- - -# Ešte lepší hack - -Nech AI kladie doplňujúce otázky. - -Príklad: - -user vyberie "reštaurácia" - -AI sa opýta: - -> Máte denné menu? -> Rezervácie? -> Donášku? -> Otváracie hodiny? - -Pri advokátovi úplne iné. - -Toto bude pôsobiť smart. - ---- - -# Architektúra (prakticky) - -Keďže ste hosting firma, šiel by som: - -wizard JSON input: +AI generuje **content layer**: ```json { - "business_type": "restaurant", - "name": "Pizza Marco", - "city": "Košice", - "services": ["pizza", "delivery"], - "style": "modern", - "pages": ["home", "menu", "contact"], - "language": ["sk"] + "hero": { + "headline": "Pizza Marco", + "subheadline": "Poctiva pizzeria v Kosiciach", + "cta_label": "Objednat" + }, + "about": { + "title": "O nas", + "body": "Sme lokalna pizzeria..." + }, + "services": [ + { + "title": "Pizza na donasku", + "description": "Rychla donaska po meste." + } + ], + "faq": [ + { + "question": "Robite donasku?", + "answer": "Ano, v ramci Kosic." + } + ] } ``` -AI output: +Rendering layer z tychto dat vytvori HTML. -* HTML/CSS/JS - alebo -* WordPress obsah + theme config - alebo -* statický web +Vyhody: -Statický web by bol MVP najjednoduchší. +* zmena sablony nevymaze obsah, +* HTML je mozne opakovane pregenerovat, +* pouzivatel nepride o data, +* buduci editor moze upravovat JSON obsah bez prepisovania HTML. --- -# Pozor na scope creep +## 5. Moduly webu -Nerob: -"full website builder" +MVP podporuje tieto moduly: -Rob: -**AI website concierge** +* uvodna sekcia, +* o nas, +* sluzby, +* cennik alebo menu, +* galeria, +* referencie, +* FAQ, +* kontakt, +* kontaktny formular. -Rozdiel obrovský. - -Builder: - -* user chce editovať všetko - -Concierge: - -* AI vytvorí web podľa odpovedí +Kazdy modul je reprezentovany v JSON datovej vrstve a renderer rozhodne, ako bude vyzerat vo vyslednom HTML. --- -# Business model čo mi tu sedí +## 6. Kontaktny formular -**Hosting + doména + AI web wizard** +Kontaktny formular ma dva rezimy. -Príklad: +### SMTP mod -**Starter** +Pouzivatel zada: -* hosting -* doména -* AI web do 5 stránok -* 1 generovanie +* SMTP host, +* port, +* username, +* password, +* encryption (`none`, `tls`, `ssl`), +* recipient email. -**Pro** +Tieto udaje sa ulozia do konfiguracie exportovaneho webu. Pri exporte sa ku webu prilozi `emailer.php`, ktory spracuje POST z formulara a odosle email. -* neobmedzené regenerácie -* viac jazykov -* AI text rewriting -* SEO suggestions +### Lokalny mod + +Ak pouzivatel SMTP nenastavi, formular zapisuje spravy do JSON suborov: + +```text +/messages/ + 2026-06-11-123456.json +``` + +Pri exporte sa prilozi `form-viewer.php`, ktory umozni jednoduche prezeranie sprav. + +Minimalne zabezpecenie: + +* heslo ulozene ako hash v konfiguracii, +* PHP session po prihlaseni, +* logout, +* ochrana pred prezeranim bez prihlasenia. --- -# Moja obava +## 7. Website Quality Requirements -Najväčší problém nebude AI. +Kazdy vygenerovany web musi splnat: -Bude to: +* mobile responsive layout pre telefon, tablet aj desktop, +* zakladne SEO meta tagy: `title`, `description`, canonical relativne k exportu ak je pouzitelne, +* OpenGraph meta tagy: `og:title`, `og:description`, `og:type`, volitelne `og:image`, +* alt texty pre vsetky obsahove obrazky, +* minimalnu accessibility: semanticke landmarky, jeden `h1`, logicka hierarchia nadpisov, citatelny kontrast, focus stavy, +* validny HTML, +* validny CSS, +* ziadne JavaScript chyby v konzole, +* ziadne externe zavislosti okrem explicitne povolenych fontov alebo obrazkov, +* relativne URL, +* fungovanie bez build procesu. -**"ešte mi presuňte to tlačidlo o 12 pixelov."** +--- -Preto by som free variant striktne uzavrel: +## 8. Biznis pravidlo proti scope creepu -> "AI vygeneruje web automaticky. Manuálne úpravy ako platená služba." +MVP je uzavrety concierge workflow. + +Pouzivatel moze: + +* zmenit odpovede vo wizard krokov, +* pregenerovat obsah, +* zmenit vizualny styl, +* exportovat web. + +Pouzivatel nemoze: + +* rucne presuvat elementy, +* editovat DOM ako v builderi, +* spravovat domenu alebo hosting priamo z MVP. + +Manualne upravy webu su mimo MVP a patria do buduceho editora alebo platenej sluzby. diff --git a/docs/specification2.md b/docs/specification2.md index 0f7e6f1..679b07b 100644 --- a/docs/specification2.md +++ b/docs/specification2.md @@ -1,122 +1,240 @@ -# WebWizard - Rozšírená Technická Špecifikácia & Architektúra +# WebWizard - Rozsirena technicka specifikacia MVP -Tento dokument nadväzuje na pôvodnú špecifikáciu a detailnejšie rozpracováva technické riešenie, architektúru a používateľskú cestu projektu WebWizard. +Tento dokument rozpracovava technicke spravanie MVP. Hlavnym zdrojom pravdy pre rozsah je `docs/mvp.md`; tento dokument doplna detaily AI workflow, renderingu a kvality vystupu. --- -## 1. Architektúra Systému +## 1. Zjednotena architektura -WebWizard je navrhnutý ako **AI Website Concierge**, ktorý premieňa štruktúrované dáta od používateľa na funkčný web. +MVP pouziva iba: -### 1.1 Komponenty -* **Frontend (Wizard UI):** Jednostránková aplikácia (Vanilla JS) s dôrazom na UX, ktorá sprevádza používateľa procesom. -* **Backend (API Layer):** Node.js (Express) alebo Python (FastAPI). Spracováva odpovede, spravuje session a komunikuje s AI. -* **AI Engine:** Integrácia s LLM (napr. GPT-4o) cez API. Používa špecifické system prompty pre rôzne segmenty biznisu. -* **Generator Service:** Modul, ktorý transformuje AI výstup (JSON/Markdown) na finálny kód (HTML/CSS/JS). -* **Storage:** - * Dočasný (Redis) pre stav rozpracovaného wizardu. - * Trvalý (S3-like) pre nahraté obrázky a vygenerované weby. +* PHP 8.2, +* JSON subory, +* Composer volitelne, +* HTML, +* CSS, +* Vanilla JavaScript, +* lokalne DAIAPI. -### 1.2 Tok dát -1. **Vstup:** Používateľ odpovedá na otázky -> JSON objekt. -2. **Spracovanie:** Backend obohatí JSON o kontextové prompty. -3. **AI Generovanie:** LLM vygeneruje textový obsah a štruktúru stránok. -4. **Templating:** Systém vyberie základnú šablónu a aplikuje vygenerovaný obsah a štýly. -5. **Výstup:** Statické súbory pripravené na nasadenie. +MVP nepouziva databazu, backend framework, frontend framework, React, Vue, Angular ani TypeScript. + +System pozostava z tychto vrstiev: + +* **Wizard UI:** Vanilla JS aplikacia, ktora zbiera odpovede. +* **PHP API layer:** `public/ajax.php` prijima AJAX poziadavky a vola akcie. +* **File storage:** JSON subory v `data/`. +* **AI queue:** JSON ulohy pre DAIAPI v `data/llm/`. +* **Content layer:** AI vystup v strukturovanom JSON. +* **Rendering layer:** PHP renderer, ktory vytvara HTML/CSS z JSON obsahu a sablon. +* **Export layer:** priecinok s hotovym statickym webom a volitelnymi PHP formularovymi skriptami. --- -## 2. Podrobný Pracovný Postup (Workflow) +## 2. Tok dat -### Krok 1: Segmentácia Biznisu (Context Discovery) -* **Akcia:** Používateľ vyberie kategóriu (napr. Reštaurácia). -* **AI logic:** Systém okamžite prispôsobuje nasledujúce otázky. -* **Smart otázky (príklady):** - * *Reštaurácia:* "Máte denné menu?", "Ponúkate donášku?" - * *Advokát:* "Špecializujete sa na rodinné, trestné alebo obchodné právo?", "Ponúkate prvú konzultáciu zdarma?" +1. Pouzivatel vyplna wizard. +2. Frontend priebezne uklada odpovede cez `saveStep`. +3. Backend validuje vstupy a uklada ich do `data/projects/.json`. +4. `generateWebsite` vytvori ulohu v `data/llm/.json`. +5. `LLMpool.php` nacita ulohu, pripravi prompt a zavola lokalne DAIAPI. +6. DAIAPI vrati iba JSON content layer. +7. Backend validuje AI JSON a ulozi ho ako `content.generated`. +8. Renderer vygeneruje `index.html`, `assets/site.css`, volitelne `assets/site.js`. +9. Export sa ulozi do `exports//`. -### Krok 2: Identita & Kontakt -* **Otázky:** Názov, Slogan, Lokalita (integrácia s Google Maps API pre autocompletion), Kontaktné údaje. - -### Krok 3: Služby a Hodnota (Content Mining) -* **UI:** Dynamické checkboxy na základe segmentu + textové pole pre "Iné". -* **Cieľ:** Získať surové dáta, ktoré AI premení na marketingovo presvedčivé texty. - -### Krok 4: Vizuálny Štýl & Branding -* **Vizuálne karty:** Minimalistický, Brutalist, Corporate, Soft/Organic. -* **Farby:** Výber palety (Primary, Secondary, Accent) alebo extrakcia z loga. -* **Logo:** Možnosť nahrať vlastné alebo vygenerovať dočasné textové logo. - -### Krok 5: Štruktúra & Moduly -* Výber modulov: FAQ, Galéria, Cenník, Kontaktný formulár, Testimonials (referencie). - -### Krok 6: Generovanie (The Magic Phase) -* Zobrazenie progress baru s vtipnými hláškami ("Trénujeme AI copywritera...", "Miešame farby...", "Staviame základy..."). +AI nesmie vracat hotove HTML. Ak DAIAPI vrati HTML, vystup sa povazuje za chybny a uloha skonci stavom `failed`. --- -## 3. Dátový Model (Input JSON) +## 3. Content layer + +Content layer je editovatelny a opakovane renderovatelny JSON obsah. + +Priklad: ```json { - "context": { - "business_type": "restaurant", - "sub_type": "italian_pizzeria", - "specific_features": ["daily_menu", "reservations", "outdoor_seating"] + "meta": { + "title": "Pizza Marco - Pizzeria v Kosiciach", + "description": "Poctiva pizzeria s donaskou a dennym menu v Kosiciach." }, - "identity": { - "name": "Bella Napoli", - "tagline": "Pravá chuť Neapola v srdci Žiliny", - "location": "Mariánske námestie 4, Žilina", - "contact": { - "phone": "+421 900 000 000", - "email": "ciao@bellanapoli.sk", - "socials": ["instagram.com/bellanapoli"] + "hero": { + "headline": "Pizza Marco", + "subheadline": "Poctiva pizza z cerstvych surovin", + "cta_label": "Kontaktovat" + }, + "about": { + "title": "O nas", + "body": "Pizza Marco je lokalna pizzeria..." + }, + "services": [ + { + "title": "Donaska pizze", + "description": "Rozvoz po Kosiciach kazdy den." } - }, - "visuals": { - "theme": "modern_elegant", - "color_scheme": { - "primary": "#E31837", - "background": "#FFFFFF", - "text": "#1A1A1A" - }, - "font_style": "serif" - }, - "content_structure": { - "pages": ["home", "menu", "gallery", "contact"], - "modules": ["faq", "instagram_feed"] - }, - "assets": { - "logo_url": "s3://path/to/logo.png", - "image_source": "ai_generated" + ], + "benefits": [ + "Cerstve suroviny", + "Rychla donaska", + "Rodinna atmosfera" + ], + "faq": [ + { + "question": "Mate denne menu?", + "answer": "Ano, aktualnu ponuku pripravujeme denne." + } + ], + "testimonials": [], + "contact_blocks": { + "phone": "+421 900 000 000", + "email": "info@pizzamarco.sk", + "address": "Hlavna 1, Kosice" } } ``` --- -## 4. Stratégia Promptovania (AI Logic) +## 4. Rendering layer -Namiesto jedného obrovského promptu použijeme **reťazenie (Chaining)**: +Renderer je deterministicka PHP vrstva. Vstupom je: -1. **Copywriting Prompt:** "Na základe týchto dát {JSON} vytvor texty pre sekcie: Hero, O nás, Služby. Použi tón hlasu: {style}. Jazyk: {lang}." -2. **Structure Prompt:** "Navrhni poradie sekcií na domovskej stránke pre {business_type} tak, aby bol konverzný pomer čo najvyšší." -3. **Styling Prompt:** "Vyber Google Fonts kombináciu, ktorá sa hodí k štýlu {visuals.theme}." +* `wizard_data`, +* AI `content.generated`, +* vybrana sablona, +* assety, +* konfiguracia formulara. + +Vystupom je exportovatelny web: + +```text +exports// + index.html + config.json + assets/ + site.css + site.js + images/ + messages/ # iba lokalny formularovy mod + emailer.php # iba SMTP mod + form-viewer.php # iba lokalny formularovy mod +``` + +Renderer zodpoveda za escapovanie HTML, relativne URL, SEO tagy, OpenGraph tagy, accessibility atributy a validny markup. --- -## 5. Technické Obmedzenia & MVP Scope +## 5. Wizard workflow -* **No-Edit Policy:** V prvej verzii (MVP) používateľ nemôže manuálne presúvať elementy. Môže len "Regenerovať sekciu" alebo "Zmeniť farby". -* **Static Export:** Výstupom je čistý HTML/CSS s minimálnym JS (napatrený Vanilla JS pre formuláre a menu). -* **Hosting:** Automatické nasadenie na subdoménu `meno-firmy.webwizard.sk`. +Kroky MVP: + +1. Segmentacia biznisu. +2. Identita, kontakt a GDPR suhlas. +3. Sluzby a smart otazky. +4. Vizualny styl a assety. +5. Moduly webu a kontaktny formular. +6. Generovanie obsahu. +7. Preview exportu. +8. Export suborov. + +Krok 2 obsahuje povinny checkbox: + +> Suhlasim so spracovanim zadanych udajov za ucelom vytvorenia webovej stranky. + +Bez suhlasu nie je mozne pokracovat. --- -## 6. Budúce Rozšírenia (Phase 2) +## 6. Promptovanie -1. **AI Image Generation:** Integrácia s DALL-E 3 / Midjourney pre generovanie tematických fotiek na mieru. -2. **SEO Autopilot:** AI automaticky vygeneruje meta tagy a alt texty k obrázkom. -3. **Booking Integrácia:** Jednoduchý rezervačný systém pre služby (kaderníctva, reštaurácie). -4. **Multi-language:** Automatický preklad celého webu jedným klikom. +Prompt musi jasne povedat: + +* vystup je iba JSON, +* nevytvaraj HTML, CSS ani JavaScript, +* zachovaj fakty z `wizard_data`, +* nevymyslaj kontaktne udaje, +* pouzi jazyk z `wizard_data.language`, +* dodaj alt texty pre obrazky, ak su zname, +* dodaj SEO title a description. + +Odporucane rozdelenie: + +* content prompt: texty, FAQ, benefity, sluzby, +* structure prompt: poradie sekcii a priorita modulov, +* metadata prompt: SEO, OpenGraph a alt texty. + +V MVP mozu byt tieto kroky spojene do jednej DAIAPI ulohy, ak vystup dodrzi jednotny JSON schema. + +--- + +## 7. Kontaktny formular + +Kontaktny formular je modul v `wizard_data.modules.contact_form`. + +### SMTP mod + +Ak pouzivatel vyplni SMTP konfiguraciu, export obsahuje `emailer.php`. + +Konfiguracia: + +```json +{ + "mode": "smtp", + "smtp": { + "host": "smtp.example.com", + "port": 587, + "username": "user@example.com", + "password": "encrypted-or-protected-value", + "encryption": "tls", + "recipient_email": "info@example.com" + } +} +``` + +### Lokalny mod + +Ak SMTP nie je nastaveny, formular zapisuje JSON spravy do `messages/`. + +Export obsahuje `form-viewer.php` so zabezpecenim: + +* prihlasenie heslom, +* hash hesla v konfiguracii, +* PHP session, +* logout. + +--- + +## 8. Website Quality Requirements + +Renderer musi pri kazdom exporte zabezpecit: + +* responzivny layout, +* validny HTML a CSS, +* zakladne SEO meta tagy, +* OpenGraph meta tagy, +* alt texty pre obsahove obrazky, +* semanticke HTML (`header`, `main`, `section`, `footer`), +* jeden hlavny `h1`, +* dostupne ovladanie klavesnicou, +* citatelny kontrast, +* ziadne runtime JavaScript chyby, +* relativne URL, +* ziadny build krok, +* ziadne nepovolene externe zavislosti. + +--- + +## 9. Mimo MVP + +Tieto oblasti su buduce rozsirene funkcionality: + +* domeny, +* DNS, +* SSL, +* automaticke nasadenie na hosting, +* vizualny drag-and-drop editor, +* online platby, +* plnohodnotna administracia klientov, +* booking system, +* viacjazycne preklady jednym klikom, +* AI generovanie obrazkov. diff --git a/docs/wizard.md b/docs/wizard.md index d390419..1deaea7 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -1,173 +1,351 @@ -# WebWizard - Detailný Návrh Sprievodcu (Wizard) +# WebWizard - Wizard MVP -Tento dokument popisuje používateľskú cestu, logiku otázok a štruktúru zberu dát pre AI generátor webstránok. +Tento dokument definuje pouzivatelsku cestu a kanonicky zber dat pre MVP. Wizard musi zbierat data tak, aby AI vytvorila strukturovany JSON obsah a renderer z neho vedel opakovane vytvorit HTML. --- -## 1. Prehľad celého wizardu - -Proces je navrhnutý tak, aby minimalizoval kognitívnu záťaž ("mentálnu náročnosť") a pôsobil ako inteligentný dialóg. +## 1. Prehlad wizardu ```ascii [ START ] | -(Krok 1) Segmentácia Biznisu <------------------+ - | | (Ak "Iné", AI vygeneruje -(Krok 2) Základná Identita | dynamické otázky) - | | -(Krok 3) Smart Otázky (Dynamicky podľa segmentu)-+ +(1) Segmentacia biznisu | -(Krok 4) Vizuálny Štýl & Branding +(2) Identita, kontakt a GDPR suhlas | -(Krok 5) Štruktúra & Moduly +(3) Sluzby a smart otazky | -(Krok 6) Magické Generovanie (Progress) +(4) Vizualny styl a assety | -(Krok 7) Interaktívny Náhľad (Preview) +(5) Moduly webu a kontaktny formular | -(Krok 8) Publikovanie & Hosting +(6) Generovanie JSON obsahu + | +(7) Preview vyrenderovaneho webu + | +(8) Export webu ``` ---- - -## 2. Detailný rozpis krokov - -### Krok 1: Segmentácia Biznisu -* **Účel:** Okamžité nastavenie kontextu pre AI. Od tohto kroku závisí tón komunikácie a ďalšie otázky. -* **Otázky:** - 1. **V akej oblasti podnikáte?** - * **Typ:** Radio cards (Ikona + Text) - * **Možnosti:** Gastro, Krása & Zdravie, Remeslá, Právne služby, IT & Kreatíva, Reality, Auto-Moto, Ubytovanie, Iné. - * **Povinné:** Áno. - 2. **Vyberte podkategóriu:** - * **Typ:** Select / Chips (Dynamicky podľa voľby vyššie). - * **Povinné:** Áno. -* **Využitie:** AI vyberie správnu "personu" a špecifický slovník (napr. pre advokáta formálny, pre kaviareň priateľský). - -### Krok 2: Základná Identita -* **Účel:** Zber faktických údajov, ktoré nesmú byť vymyslené AI. -* **Otázky:** - 1. **Názov vašej firmy / projektu:** (Text, Povinné) - 2. **Váš slogan (ak máte):** (Text, Voliteľné - ak chýba, AI navrhne 3 varianty v náhľade) - 3. **Kde vás zákazníci nájdu?** (Text, Voliteľné - pre online biznis netreba) - 4. **Kontaktné údaje (Tel/Email):** (Text, Povinné) -* **Využitie:** Naplnenie hlavičky (Header), päty (Footer) a kontaktnej sekcie. - -### Krok 3: Smart Otázky (Dynamicky podľa segmentu) -* **Účel:** Získať "expertízu", vďaka ktorej web nebude pôsobiť genericky. -* **Príklady otázok (viď sekciu 5 pre detaily):** - * *Reštaurácia:* "Máte denné menu?", "Prijímate rezervácie?" - * *Remeselník:* "Ponúkate havarijnú službu 24/7?", "Máte certifikáty?" -* **Využitie:** AI vytvorí špeciálne bloky obsahu (napr. rezervačný formulár, tabuľka s otváracími hodinami). - -### Krok 4: Vizuálny Štýl & Branding -* **Účel:** Určenie estetického smerovania bez nutnosti byť grafikom. -* **Otázky:** - 1. **Aký štýl sa vám páči?** - * **Typ:** Vizuálne karty (Náhľad dizajnu) - * **Možnosti:** Minimalistický, Luxusný, Firemný, Kreatívny, Technický. - 2. **Vyberte si farebnú paletu:** - * **Typ:** Farebné presety (3 ladiace farby) alebo Color Picker. - 3. **Máte logo?** - * **Typ:** Upload / "Nemám, vygenerujte mi textové". -* **Využitie:** Generovanie CSS premenných a výber Google Fonts. - -### Krok 5: Štruktúra & Moduly -* **Účel:** Definícia rozsahu webu. -* **Otázka:** Čo má váš web obsahovať? - * **Typ:** Checkbox list. - * **Možnosti:** O nás, Služby, Cenník, Galéria fotiek, FAQ, Referencie zákazníkov, Kontaktný formulár. -* **Využitie:** AI vygeneruje sekcie na domovskej stránke (Single Page design). +Wizard nesluzi ako vizualny editor. Sluzi na zber rozhodnuti a faktov. --- -## 3. Typy podnikania (Kategorizácia) +## 2. Krok 1 - Segmentacia biznisu -| Skupina | Podkategórie | +Ucel: nastavit kontext, ton komunikacie, smart otazky a predvolene moduly. + +Polia: + +* `business_category.group` - hlavna skupina, +* `business_category.subcategory` - podkategoria, +* `business_category.custom_description` - vlastny typ, ak pouzivatel zvoli "Ine". + +Typ UI: + +* radio cards pre hlavne skupiny, +* chips alebo select pre podkategorie, +* textove pole pre "Ine". + +Priklady skupin: + +| Skupina | Podkategorie | | :--- | :--- | -| **Gastro** | Reštaurácia, Kaviareň, Bistro, Donáška, Vináreň, Cukráreň | -| **Krása & Zdravie** | Kaderníctvo, Kozmetika, Barber, Zubná ambulancia, Masáže, Fitness | -| **Remeslá** | Inštalatér, Elektrikár, Stolár, Maliar, Hodinový manžel, Kominár | -| **Právne & Fin. služby** | Advokát, Účtovník, Notár, Finančný poradca, Exekútor | -| **Auto-Moto** | Autoservis, Pneuservis, Autopožičovňa, Detailing, Autoškola | -| **IT & Kreatíva** | Programátor, Grafik, Fotograf, Marketingová agentúra, Copywriter | -| **Reality & Staveb.** | Realitná kancelária, Architekt, Správa budov, Stavebná firma | -| **Vzdelávanie** | Doučovanie, Jazyková škola, Škôlka, Umelecká škola | +| Gastro | Restauracia, Kaviaren, Bistro, Donaska, Vinaren, Cukraren | +| Krasa & Zdravie | Kadernictvo, Kozmetika, Barber, Zubna ambulancia, Masaze, Fitness | +| Remesla | Instalater, Elektrikar, Stolar, Maliar, Hodinovy manzel, Kominar | +| Pravo & Financie | Advokat, Uctovnik, Notar, Financny poradca | +| Auto-Moto | Autoservis, Pneuservis, Autopozicovna, Detailing, Autoskola | +| IT & Kreativa | Programator, Grafik, Fotograf, Marketingova agentura, Copywriter | +| Reality & Stavby | Realitna kancelaria, Architekt, Sprava budov, Stavebna firma | +| Vzdelavanie | Doucovanie, Jazykova skola, Skolka, Umelecka skola | + +Ak pouzivatel zvoli "Ine", backend moze cez DAIAPI navrhnut 3 smart otazky. Navrhy sa ulozia do `data/admin/pending_categories.json`. --- -## 4. Dynamické otázky (Príklady) +## 3. Krok 2 - Identita, kontakt a GDPR suhlas -* **Gastro:** - * Ponúkate rozvoz jedla? (Áno/Nie) - * Máte špeciálne denné menu? (Áno/Nie) - * Prijímate online rezervácie stolov? (Áno/Nie) -* **Ubytovanie:** - * Počet izieb/kapacita? (Číslo) - * Čas Check-in a Check-out? (Text) - * Ponúkate parkovanie a WiFi v cene? (Checkboxy) -* **Právne služby:** - * V ktorých oblastiach práva pôsobíte? (Chips: Trestné, Rodinné, Obchodné...) - * Ponúkate prvú konzultáciu zdarma? (Áno/Nie) -* **Auto-Moto:** - * Ktoré značky servisujete? (Text/Všetky) - * Máte odťahovú službu? (Áno/Nie) +Ucel: ziskat fakty, ktore AI nesmie vymyslat. + +Polia: + +* `identity.business_name` - povinne, +* `identity.tagline` - volitelne, +* `identity.description` - volitelne, +* `contact.email` - povinne, ak chyba telefon, +* `contact.phone` - povinne, ak chyba email, +* `contact.address` - volitelne, +* `contact.city` - volitelne, +* `contact.region` - volitelne, +* `contact.socials` - volitelne. + +GDPR checkbox je povinny: + +> Suhlasim so spracovanim zadanych udajov za ucelom vytvorenia webovej stranky. + +Bez zaskrtnutia nie je mozne pokracovat. Backend uklada: + +* `accepted: true`, +* `accepted_at` v UTC, +* `consent_text_version`, +* presny text suhlasu, +* `project_id`, +* `user_id`. --- -## 5. Riešenie pre neznámy typ ("Iné") +## 4. Krok 3 - Sluzby a smart otazky -Ak používateľ nenájde svoju kategóriu, aktivuje sa **AI Concierge Workflow**: +Ucel: ziskat obsahove vstupy, vdaka ktorym web nebude genericky. -1. **Vstup:** Používateľ zvolí "Iné" a napíše: "Chovateľ včiel a predaj medu". -2. **AI Analýza:** Backend okamžite pošle tento text DAIAPI. -3. **Real-time generovanie:** AI vráti 3 relevantné otázky: - * "Máte vlastný e-shop alebo len osobný odber?" - * "Ponúkate exkurzie na včelnicu?" - * "Máte certifikát BIO kvality?" -4. **Kontinuita:** Používateľ tieto otázky dostane v Kroku 3, akoby boli v systéme odjakživa. -5. **Uloženie:** Systém zapíše túto novú kategóriu do `data/admin/pending_categories.json`. +Polia: + +* `services.items[]` - nazov, popis, volitelne cena od, +* `services.pricing_note` - poznamka k cenniku, +* `smart_answers` - odpovede na dynamicke otazky. + +Priklady smart otazok: + +* Gastro: donaska, denne menu, rezervacie, otvaracie hodiny. +* Ubytovanie: kapacita, check-in/check-out, parkovanie, WiFi. +* Pravo: oblasti prava, prva konzultacia, jazyk konzultacie. +* Auto-Moto: servisovane znacky, odtah, diagnostika, pneuservis. + +UI: + +* checkboxy, +* chips, +* kratke textove polia, +* tlacidlo "Preskocit a nechat na AI" pre volitelne otazky. --- -## 6. Administrácia (JSON Štruktúra) +## 5. Krok 4 - Vizualny styl a assety + +Ucel: urcit dizajnovy smer bez potreby grafika. + +Polia: + +* `visuals.style` - napriklad `minimal`, `modern`, `premium`, `corporate`, `creative`, `technical`, +* `visuals.color_scheme.primary`, +* `visuals.color_scheme.secondary`, +* `visuals.color_scheme.accent`, +* `visuals.color_scheme.background`, +* `visuals.color_scheme.text`, +* `visuals.font_style` - `sans`, `serif`, `mixed`, +* `visuals.layout_density` - `compact`, `comfortable`, `spacious`, +* `assets.logo`, +* `assets.images[]`, +* `assets.image_source` - `uploaded`, `none`, `placeholder`. + +Uploady: + +* povolene obrazkove formaty: jpg, jpeg, png, webp, svg iba po sanitizacii, +* limit velkosti suboru definuje backend, +* kazdy obrazok ma mat alt text alebo AI navrh alt textu. + +--- + +## 6. Krok 5 - Moduly webu a kontaktny formular + +Ucel: definovat rozsah vysledneho webu. + +Polia: + +* `modules.pages` - v MVP typicky `["home"]`, +* `modules.sections` - zoznam sekcii, +* `modules.contact_form.enabled`, +* `modules.contact_form.mode`, +* `modules.contact_form.smtp`, +* `modules.contact_form.local_viewer`. + +Dostupne sekcie: + +* hero, +* about, +* services, +* pricing, +* gallery, +* testimonials, +* faq, +* contact. + +### Kontaktny formular + +Ak je formular zapnuty, pouzivatel si vyberie rezim. + +SMTP mod: + +* SMTP host, +* port, +* username, +* password, +* encryption, +* recipient email. + +Lokalny mod: + +* formular uklada spravy do `messages/`, +* export obsahuje `form-viewer.php`, +* pouzivatel zada heslo pre prezeranie sprav, +* heslo sa uklada iba ako hash. + +--- + +## 7. Krok 6 - Generovanie JSON obsahu + +Frontend zavola `generateWebsite`. Backend zaradi AI ulohu do fronty. + +DAIAPI dostane `wizard_data` a vrati content JSON. AI nesmie vratit HTML. + +Priklady vygenerovanych casti: + +* SEO title a description, +* hero headline, +* text O nas, +* popisy sluzieb, +* benefity, +* FAQ, +* referencie, ak pouzivatel dodal vstupy, +* kontaktne bloky. + +--- + +## 8. Krok 7 - Preview + +Preview zobrazuje vysledok renderingu, nie AI HTML. + +Pouzivatel moze: + +* pregenerovat obsah, +* vratit sa do wizardu a zmenit vstupy, +* zmenit vizualny styl, +* pregenerovat HTML z existujuceho JSON obsahu, +* exportovat web. + +Pouzivatel nemoze v MVP rucne presuvat elementy ani upravovat DOM. + +--- + +## 9. Krok 8 - Export webu + +MVP vytvara exportovatelny priecinok. Neriesi domenu, DNS, SSL ani automaticke nasadenie. + +Export obsahuje: + +* `index.html`, +* `config.json`, +* `assets/site.css`, +* volitelne `assets/site.js`, +* obrazky, +* `emailer.php` pri SMTP formulari, +* `form-viewer.php` a `messages/` pri lokalnom formulari. + +Vsetky URL musia byt relativne. + +--- + +## 10. Wizard Data Schema + +Kanonicky model: -### `data/categories.json` (Definícia) ```json { - "gastro": { - "label": "Gastro", - "subcategories": ["restaurant", "cafe", "bistro"], - "smart_questions": [ - { "id": "delivery", "label": "Ponúkate rozvoz?", "type": "boolean" }, - { "id": "menu", "label": "Máte denné menu?", "type": "boolean" } - ] - } -} -``` - -### `data/admin/pending_categories.json` (AI návrhy) -```json -{ - "bee_farmer": { - "original_input": "Chovateľ včiel", - "ai_generated_questions": [ - { "id": "q1", "label": "Máte BIO certifikát?", "type": "boolean" } + "identity": { + "business_name": "Pizza Marco", + "tagline": "Poctiva pizza v Kosiciach", + "description": "Rodinna pizzeria" + }, + "contact": { + "email": "info@pizzamarco.sk", + "phone": "+421 900 000 000", + "address": "Hlavna 1", + "city": "Kosice", + "region": "Kosicky kraj", + "socials": { + "facebook": "https://facebook.com/pizzamarco" + } + }, + "services": { + "items": [ + { + "name": "Donaska pizze", + "description": "Rozvoz po meste", + "price_from": "7 EUR" + } ], - "usage_count": 1, - "status": "pending" + "pricing_note": "Ceny su orientacne." + }, + "visuals": { + "style": "modern", + "color_scheme": { + "primary": "#C62828", + "secondary": "#F8F1E7", + "accent": "#2E7D32", + "background": "#FFFFFF", + "text": "#1A1A1A" + }, + "font_style": "sans", + "layout_density": "comfortable" + }, + "modules": { + "pages": ["home"], + "sections": ["hero", "about", "services", "faq", "contact"], + "contact_form": { + "enabled": true, + "mode": "local", + "smtp": null, + "local_viewer": { + "password_hash": "$2y$..." + } + } + }, + "assets": { + "logo": { + "uploaded": true, + "path": "assets/images/logo.png", + "alt": "Logo Pizza Marco" + }, + "images": [ + { + "path": "assets/images/pizza.jpg", + "alt": "Cerstva pizza" + } + ], + "image_source": "uploaded" + }, + "language": { + "primary": "sk", + "additional": [], + "tone": "friendly" + }, + "business_category": { + "group": "gastro", + "subcategory": "restaurant", + "custom_description": null + }, + "smart_answers": { + "delivery": true, + "daily_menu": true, + "reservations": false } } ``` --- -## 7. Minimalizácia počtu otázok (Optimization) +## 11. Website Quality Requirements -| Stratégia | Implementácia | -| :--- | :--- | -| **Povinné minimum** | Iba Názov, Email a Typ biznisu. Ostatné je dobrovoľné. | -| **AI Inference** | Ak používateľ napíše názov "Pizzeria u Petra", AI v Kroku 1 automaticky predvolí "Gastro -> Reštaurácia". | -| **Defaulting** | Vizuálny štýl je prednastavený na "Minimalistický" - používateľ môže len kliknúť "Ďalej". | -| **Skip Option** | Každý krok (okrem 1 a 2) má tlačidlo "Preskočiť a nechať na AI". | -| **Smart Defaults** | Otázky v Kroku 5 (Obsah) sú vopred zaškrtnuté podľa typu biznisu (napr. pre reštauráciu je "Cenník/Menu" automaticky ON). | +Wizard musi zbierat dostatok informacii na to, aby renderer vedel splnit: + +* mobile responsive design, +* zakladne SEO meta tagy, +* OpenGraph meta tagy, +* alt texty pre obrazky, +* minimalne accessibility poziadavky, +* validny HTML, +* validny CSS, +* ziadne JavaScript chyby, +* ziadne nepovolene externe zavislosti, +* relativne URL, +* fungovanie bez build procesu.