WebWizard/docs/wizard.md

WebWizard - Wizard MVP

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. Prehlad wizardu

[ START ]
    |
(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

Wizard nesluzi ako vizualny editor. Sluzi na zber rozhodnuti a faktov.

---

2. Krok 1 - Segmentacia biznisu

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	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.

---

3. Krok 2 - Identita, kontakt a GDPR suhlas

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.

---

4. Krok 3 - Sluzby a smart otazky

Ucel: ziskat obsahove vstupy, vdaka ktorym web nebude genericky.

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.

---

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:

{
  "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"
      }
    ],
    "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
  }
}

---

11. Website Quality Requirements

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.