merged data info and created one mvp.md
This commit is contained in:
@ -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/<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>/`.
|
||||
|
||||
### 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/<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. 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.
|
||||
|
||||
Reference in New Issue
Block a user