WebWizard/docs/specification2.md

WebWizard - Rozsirena technicka specifikacia MVP

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

MVP pouziva iba:

• PHP 8.2,
• JSON subory,
• Composer volitelne,
• HTML,
• CSS,
• Vanilla JavaScript,
• lokalne DAIAPI.

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

1. Pouzivatel vyplna wizard.
2. Frontend priebezne uklada odpovede cez saveStep.
3. Backend validuje vstupy a uklada ich do data/projects/<project_id>.json.
4. generateWebsite vytvori ulohu v data/llm/<task_id>.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/<project_id>/.

AI nesmie vracat hotove HTML. Ak DAIAPI vrati HTML, vystup sa povazuje za chybny a uloha skonci stavom failed.

---

3. Content layer

Content layer je editovatelny a opakovane renderovatelny JSON obsah.

Priklad:

{
  "meta": {
    "title": "Pizza Marco - Pizzeria v Kosiciach",
    "description": "Poctiva pizzeria s donaskou a dennym menu v Kosiciach."
  },
  "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."
    }
  ],
  "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. Rendering layer

Renderer je deterministicka PHP vrstva. Vstupom je:

• wizard_data,
• AI content.generated,
• vybrana sablona,
• assety,
• konfiguracia formulara.

Vystupom je exportovatelny web:

exports/<project_id>/
  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. Wizard workflow

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

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:

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