diff --git a/docs/fejlesztesi_terv_mozdit.md b/docs/fejlesztesi_terv_mozdit.md new file mode 100644 index 0000000..b772837 --- /dev/null +++ b/docs/fejlesztesi_terv_mozdit.md @@ -0,0 +1,463 @@ +# mozdIT Bt. Weboldal Fejlesztési Terv (MVP) + +## Vezetői Összefoglaló + +### Projekt Célja +Megbízható, mobil-első bemutatkozó weboldal fejlesztése a mozdIT Bt. számára, amely kiemeli személyes ügyfélkezelésüket és webhely szolgáltatásaikat. Az oldalnak profi megjelenést, gyors teljesítményt és könnyű használhatóságot kell biztosítania. + +### Főbb Projekt Célkitűzések +- **2 hét alatt** prototípus + **3 hét alatt** MVP verzió elkészítése és élesítés +- Korai validáció teljes fejlesztési és deployment folyamatra +- Agile megközelítés: prototípus alapú fokozatos fejlesztés +- **Teljesítmény**: Lighthouse ≥ 90 mobileszközön és desktopon +- **Elérhetőség**: WCAG 2.1 AA szabvány teljesítése +- **Biztonság**: HTTPS, alapvető CSP és input validáció +- **Skálázhatóság**: Admin felület helye előkészítve későbbi fejlesztéshez + +--- + +## Projektek Architektúra és Technológiai Stacket + +### Frontend Technológia Stack +``` +Next.js 14+ (App Router + TypeScript) +├── Tailwind CSS (styling + shadcn/ui opcionális) +├── React Hook Form + Zod (form kezelés és validáció) +├── React Testing Library + Jest (unit tesztek) +└── Behave + Gherkin (behavior-driven E2E tesztek) +``` + +### Deployment és Infrastruktúra +``` +Dokploy Platform +├── Docker container (multi-stage build) +├── Nginx/Traefik reverse proxy +├── Let’s Encrypt SSL automatikus +└── GitHub Actions CI/CD pipeline +``` + +### Márkázás és Design +- **Primary Colors**: IT szektor konzisztens színvilága +- **Typography**: Modern, olvasható betűtípusok +- **Logo Assets**: Kialakított logók használata (PNG/JPG formátumban) +- **Branding**: Személyes ügyfélkezelés és megbízhatóság hangsúlyozása + +--- + +## Fejlesztési Fázisok és Mérföldkövek + +### Fázis 0: Prototípus és Pipeline Tesztelés (3-4 nap) +**Cél**: Egyszerű működő alap elkészítése a teljes fejlesztési és deployment folyamat demonstrálására + +#### 0.1 Egyszerű Weboldal és Backend +```bash +# Gyors Next.js setup primitív funkcióval +npx create-next-app@latest --typescript --tailwind --yes mozdit-proto +cd mozdit-proto + +# Minimal backend API route +# app/api/hello/route.ts - egyszerű JSON válasz +# app/page.tsx - alapvető oldal egy "Hello World" üzenettel + +# Adjon hozzá egyszerű form-ot adatgyűjtéshez (név, email) +# Store adatok egyszerű JSON fájlban vagy in-memory +``` + +#### 0.2 Primitív Adattárolás +- SQLite vagy egyszerű JSON fájlok kezdetben +- Egy egyszerű adatbázis tábla user adatok tárolására +- Basic CRUD műveletek tesztelése + +#### 0.3 Teljes Deployment Tesztelés +```bash +# Dokploy telepítés és alap konfiguráció +# Staging környezeten teljes CI/CD pipeline kipróbálása +# Automatikus deployment build → test → deploy → monitoring +``` + +**Agile Megközelítés Előnyei:** +- Riszkócsökkentés: Pipeline és infrastruktúra tesztelése korán +- Feedback ciklus: Gyors tanulás és iteráció +- Alap megteremtése: Ez a prototípus szolgál a későbbi funkciók alapjául +- Dokumentáció: A folyamat minden lépése dokumentálva későbbi fejlesztésekhez + +**Mérföldkő**: Futtatható prototípus staging környezetben, teljes pipeline működik + +--- + +### Fázis 1: Projekt Inicializálás (1 hét) +**Cél**: Projekt alapjának létrehozása és alapvető infrastrukturának beállítása + +#### 1.1 Repository és Boilerplate Beállítása +```bash +# Next.js 14 projekt inicializálás TypeScript-tel +npx create-next-app@latest mozdit-web --typescript --tailwind --src-dir +cd mozdit-web + +# Alapvető dependency-k hozzáadása +npm install @hookform/resolvers zod react-hook-form +npm install -D @playwright/test @testing-library/react @testing-library/jest-dom +``` + +#### 1.2 CI/CD Pipeline Beállítása +- GitHub Actions workflow létrehozása (lint → test → build) +- Prettier és ESLint konfiguráció +- Husky pre-commit hookok + +#### 1.3 Dokploy Staging Környezet +- Dokploy telepítés és konfiguráció +- Staging alkalmazás létrehozása (`staging.mozdit.hu`) +- Environment változók beállítása +- Docker multi-stage build konfiguráció + +**Mérföldkő**: Futtatható dev környezet staging deploy képességgel + +--- + +### Fázis 2: Core Felhasználói Felületek (2 hét) +**Cél**: MVP oldalak (Hom, Rólunk, Szolgáltatások, Kapcsolat) implementálása + +#### 2.1 Lapozás és Reszponzív Layout +**Technikai követelmények:** +- Mobile-first responsive design (320px → 1280px+) +- Sticky navigation hamburger mobile nézettel +- SEO alapok (title/description, OG meta tags) +- sitemap.xml és robots.txt generálása + +#### 2.2 Tartalom Komponensek + +##### Kezdőlap (Hero + CTA + Szolgáltatás Kártyák) +```typescript +interface ServiceCard { + title: string; + description: string; + icon: React.ComponentType; + ctaText: string; + ctaLink: string; +} + +const heroContent = { + title: "Megbízható web‑ és email‑szolgáltatás **személyre szabott támogatással**.", + subtitle: "Kis ügyfélkör, nagy figyelem...", + ctaButton: "Webmail Ugrás", + ctaLink: "https://webmail.mozdit.hu" +}; +``` + +##### Kapcsolat Űrlap +- **Frontend**: React Hook Form + Zod validáció +- **Backend**: API Route `/api/contact` (form küldés) +- **Biztonság**: Spam védelem, input sanitizáció +- **Validáció**: Név, email, üzenet, GDPR consent + +#### 2.3 Form Hibakezelés és Validáció +```typescript +// Zod schema Hungarian üzenetekkel +const contactSchema = z.object({ + name: z.string().min(2, "Név legalább 2 karakter"), + email: z.string().email("Érvénytelen email cím"), + message: z.string().min(10, "Üzenet túl rövid"), + consent: z.boolean().refine(val => val, "Kérjük fogadja el az adatkezelési tájékoztatót") +}); +``` + +**Mérföldkő**: Minden oldal teljes funkcionalitással staging környezetben + +--- + +### Fázis 3: Minőségbiztosítás és Optimalizálás (1 hét) +**Cél**: Teljesítmény, biztonság és felhasználói élmény finomhangolása + +#### 3.1 Teljesítmény Optimalizálás + +**Mi az a Lighthouse?** +A **Lighthouse** a Google által fejlesztett nyílt forráskódú eszköz weboldalak teljesítményének, hozzáférhetőségének, SEO-jának és legjobb gyakorlatainak automatikus elemzéséhez. Pontszámokat ad (0-100) különböző kategóriákban: + +- **Performance**: Oldal betöltési sebessége és reszponzivitása +- **Accessibility (A11Y)**: Akadálymentességi szabványok teljesítése +- **Best Practices**: Modern webfejlesztési gyakorlatok alkalmazása +- **SEO**: Keresőoptimalizálási szempontok +- **Progressive Web App (PWA)**: Alkalmazásszerű funkcionalitás + +**Célkitűzések:** +- Lighthouse mobil: ≥ 90 minden metrikában +- Lighthouse desktop: ≥ 90 minden metrikában +- Core Web Vitals megfelelés + +**Technikai implementáció:** +- **Next.js optimális**: `next/image` lazy load, font optimalizálás +- **CSS optimalizálás**: kritikus CSS inline, unused CSS eltávolítása +- **WebP/AVIF képek**: automatikus konverzió és optimalizálás +- **Bundle analízis**: Webpack bundle analyzer használata + +#### 3.2 Akadálymentesség (A11Y) +**WCAG 2.1 AA követelmények:** +- Kontraszt arány legalább 4.5:1 (Figma/JPG alapján beállítandó) +- Fókuszkezelés (keyboard navigation) +- ARIA címkék és semantic HTML +- Screen reader kompatibilitás + +#### 3.3 Biztonság és Monitoring +```typescript +// Basic CSP fejlécek +const securityHeaders = [ + { key: 'X-Frame-Options', value: 'SAMEORIGIN' }, + { key: 'X-Content-Type-Options', value: 'nosniff' }, + { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' }, + { + key: 'Content-Security-Policy', + value: "default-src 'self'; script-src 'self' 'unsafe-inline' *.google-analytics.com;" + } +]; +``` + +#### 3.4 Testing és QA +**Teszt stratégia:** +- **Unit tesztek**: Komponens logika és utility függvények (Jest + Testing Library) +- **Behavior-Driven tesztek**: Kritikus felhasználói流程-ok természetes nyelven (Behave + Gherkin) +- **Performancia tesztek**: Lighthouse CI és Web Vitals monitoring élesítés előtt +- **Smoke tesztek**: Deploy után alapfunkciók ellenőrzése +- **Visual regression**: Design konzisztencia ellenőrzés + +#### Gherkin Behavior-Driven Tesztelés +**Előnyök:** +- **Üzleti együttműködés**: Természetes nyelvű tesztek (Given/When/Then) - nem technikai közönség is érti +- **Dokumentáció**: Teszt esetek egyben élő követelmény dokumentáció +- **Karbantarthatóság**: Változások esetén könnyebb megérteni mit kell módosítani +- **Coverage**: Fontos üzleti folyamatok teljes lefedettsége + +**Példa Gherkin teszt eset:** +```gherkin +Felhasználóként szeretnék érdeklődni szolgáltatásaikról +Ha megadom adataimat és érdeklődésemet +Majd visszaigazoló üzenetet szeretnék kapni + +Körülmények: Kapcsolat oldal aktív +Mikor: kitöltöm a másolat űrlapot (név, email, üzenet) +Történik: form küldés után visszaigazolás jelenik meg +``` + +**Mérföldkő**: Staging környezet teljes Lighthouse 90+ és A11Y compliance + +--- + +### Fázis 4: Élesítés és Monitoring (1 hét) +**Cél**: Production deployment, monitoring és visszajelzés gyűjtés + +#### 4.1 Production Deploy +- Dokploy production alkalmazás konfiguráció +- Domain routing (`www.mozdit.hu` → `mozdit.hu`) +- HTTPS automatikus (Let’s Encrypt) +- Environment változók production értékei + +#### 4.2 Monitoring Beállítása +```typescript +// Health check endpoint +export async function GET() { + return Response.json({ + status: 'ok', + timestamp: new Date().toISOString(), + version: process.env.npm_package_version + }); +} +``` + +- Sentry frontend monitoring telepítése +- Plausible analitika (gdpr-kompatibilis) +- Performance monitoring dashboards +- Error tracking és alerting + +#### 4.2 Go-live Checklist +- [ ] Production domain DNS propagáció ✅ +- [ ] SSL tanúsítvány aktív ✅ +- [ ] HTTPS redirections helyesek ✅ +- [ ] Contact form működik ✅ +- [ ] Webmail link helyes ✅ +- [ ] Performancia teszt: Lighthouse 90+ mobilon és desktopon ✅ +- [ ] 404/500 oldalak kezelve ✅ +- [ ] Final performance audit eredmények dokumentálva ✅ + +**Mérföldkő**: Élő website production környezetben, teljes monitoring aktív + +--- + +## Risk Assessment és Mitigation + +### Magas Kockázatú Területek + +#### 1. Performance Issues +**Valószínűség**: Közép **Hatása**: Magas +**Mitigáció**: +- Korai teljesítmény auditok minden fejlesztési fázis után +- Web Vitals monitoring folyamatos +- Incremental image optimalizálás + +#### 2. Form Security +**Valószínűség**: Közép **Hatása**: Magas +**Mitigáció**: +- Server-side validáció kötelező +- CSRF és XSS védelem alapértelmezett +- Rate limiting implementáció + +#### 3. Third-party Dependencies +**Valószínűség**: Alacsony **Hatása**: Közép +**Mitigáció**: +- Minimális dependency használata MVP esetén +- Security audit npm audit használata +- Lock file használata verzió stabilitásért + +#### 4. Browser Compatibility +**Valószínűség**: Alacsony **Hatása**: Alacsony +**Mitigáció**: +- Modern browser támogatás (Chrome, Firefox, Safari, Edge) +- Polyfill minimális használata +- CSS Grid és Flexbox alapértelmezett + +--- + +## Architektúrális Döntések Indoklása + +### Next.js Valasztása React helyett +- **SEO**: Server-Side Rendering oldalbetöltési sebességért +- **Performance**: Automatikus optimalizálások (code splitting, minification) +- **Developer Experience**: TypeScript first-class support, hot reload +- **Ecosystem**: Nagy közösség, stabil könyvtárak rengeteg + +### Dokploy Deployment Platform +- **Költséghatékonyság**: €4-20/hó vs managed PaaS €50+ +- **Teljes kontroll**: Saját szerver, custom Docker konfiguráció +- **Biztonság**: Magán infrastruktúra, adatvédelmet könnyebb teljesíteni +- **Skálázhatóság**: Multi-server support későbbi növekedéshez + +### Mobile-First Approach +- **Használat**: Magyar IT piac ~70% mobile üzemeltetés +- **Performance**: Mobil prioritás segíti desktop teljesítményt is +- **User Experience**: Progressív enhancement elvén +- **Business Impact**: Célközönség (KKV-k) többsége mobilról használ + +### Plausible Analytics (GDPR Compliance) +- **Cookie-free**: Nem használ cookie-kat követéshez +- **Privacy-focused**: EU adatvédelmi előírásoknak megfelel +- **Performance**: Lightweight, nem lassítja az oldalt +- **Magyar piac**: Stricter adatvédelmi követelmények + +--- + +## Kommunikáció és Projekt Management + +### Team Kommunikáció +- **Napi standup**: Progress jelentés és blocker azonosítás +- **Weekly demo**: Áttekintés és visszajelzés gyűjtés +- **GitHub Issues**: Feladatkövetés és dokumentáció +- **Dokploy Dashboard**: Deploy status és monitoring + +### Stakeholder Kommunikáció +- **Heti előrehaladási jelentések**: Vizualizált mérföldkövek +- **Sprint demo-k**: Új funkciók bemutatása +- **Production go-live**: Timeline és rollback terv +- **Monitoring telepítés**: Post-launch visszajelzés + +--- + +## Projekt Workflow és Időzítés + +```mermaid +graph TB + subgraph "Fázis 0: Prototípus (3-4 nap)" + P1[Simple weboldal] --> P2[Primitív backend] + P2 --> P3[Háttér DB tesztelés] + P3 --> P4[Deployment próbája] + end + + subgraph "Fázis 1: Inicializálás (1 hét)" + A1[Repository setup] --> A2[Dokploy staging] + A2 --> A3[CI/CD pipeline] + A3 --> A4[Environment config] + end + + subgraph "Fázis 2: Core UI (2 hét)" + B1[Responsive layout] --> B2[Hero + services] + B2 --> B3[About page] + B3 --> B4[Contact form] + B4 --> B5[SEO basics] + end + + subgraph "Fázis 3: QA & Optim (1 hét)" + C1[Lighthouse testing] --> C2[A11Y audit] + C2 --> C3[Security setup] + C3 --> C4[E2E testing] + end + + subgraph "Fázis 4: Production (1 hét)" + D1[Prod deployment] --> D2[Monitoring setup] + D2 --> D3[Performance monitoring] + D3 --> D4[Go-live checklist] + end + + P4 --> A1 + A4 --> B1 + B5 --> C1 + C4 --> D1 + + style P1 fill:#ffebee + style A1 fill:#e1f5fe + style B1 fill:#f3e5f5 + style C1 fill:#e8f5e8 + style D1 fill:#fff3e0 +``` + +### Projekt Timeline +``` +Nap 1-4 Hét 1 Hét 2-3 Hét 4 Hét 5 +│ │ │ │ │ +├── Fázis 0 ├── Fázis 1 ├── Fázis 2 ├── Fázis 3 ├── Fázis 4 +│ Prototípus ├── Setup ├── Core UI ├── QA ├── Production +│ Pipeline │ Dokploy │ Pages │ Testing │ Deploy +│ tesztelés │ Pipeline │ Forms │ Security │ Monitoring +``` + +--- + +## Utó-mérföldkövek és Bővítmények + +### Utáni Fejlesztési Prioritások +1. **Admin Felület** (`/admin` route aktiválás) +2. **Content Management** (Markdown alapú tartalom szerkesztés) +3. **Blog/Cikkek** (SEO tartalom generálás) +4. **Multilingvális Támogatás** (Magyar + Angol) +5. **Analytics Dashboard** (hasznosítás adatok alapján) + +### Scaling Considerations +- Database integráció (PostgreSQL) nagyobb tartalomhoz +- CDN implementáció (Cloudflare) globális terjesztéshez +- Redis cache réteg teljesítmény optimalizáláshoz +- Load balancer multi-instance deployment-hez + +--- + +## Success Metrics + +### Technikai KPIs +- **Performance**: Lighthouse 90+ összes platformon +- **Availability**: 99.9% uptime monitoringgal +- **Security**: Zero security vulnerabilities deployment után +- **Accessibility**: WCAG 2.1 AA teljes megfelelés + +### Üzleti KPIs +- **Traffic**: Legalább 100 unikális látogató/hó kezdetben +- **Engagement**: Átlag 2+ oldal megtekintés/session +- **Conversions**: Kapcsolat felvételi űrlap használat minimum 5%/hó +- **SEO**: Google Search Console beállítással + +### Szoftver Minőség KPIs +- **Test Coverage**: 80%+ unit és integration coverage +- **Code Quality**: ESLint és Prettier compliance +- ~~Bug Rate~~: Max 0.1 bug per feature deployment után +- **Deploy Success Rate**: 95%+ automatikus deployment sikerességi arány + +--- + +*Ez a fejlesztési terv a docs/ könyvtárban található dokumentumokon alapul és biztosítja a mozdIT Bt. üzleti igényeinek megfelelő, szakmai színvonalú megvalósítást. A terv iteratív jellegű, az actual eredmények alapján finomhangolható.* + +*Projekt Manager: Architektúra Csapat* +*Utolsó frissítés: 2025. szeptember 4.* \ No newline at end of file