Add initial project documentation

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-02 21:53:36 +02:00
parent ef168dc080
commit 777f53da4b
7 changed files with 2214 additions and 0 deletions
@@ -0,0 +1,236 @@
+# mozdIT Bt. — Weboldal követelmény + Dokploy deploy specifikáció (MVP)
+
+## 0) Rövid összefoglaló
+Cél: minimális, de komplett, mobil‑első, gyors és biztonságos **bemutatkozó weboldal** a mozdIT Bt.-nek, kiemelt **Webmail** linkkel és rövid, egyedi bemutatkozással. A később készülő **admin aloldal** (szerver‑monitoring/menedzsment) helye előkészítve. Deployment és tesztelés: **Dokploy** környezetben.
+
+---
+
+## 1) MVP oldalak és funkciók
+**Oldalak**
+- **Kezdőlap**: rövid, egyedi bemutatkozó szöveg; CTA: **Webmail** link (külső URL); szolgáltatások rövid dobozai.
+- **Rólunk**: rövid történet, működés óta, személyes ügyfélkezelés, megbízhatóság.
+- **Szolgáltatások**: web hosting, email szolgáltatás, DNS adminisztráció (rövid leírás + kapcsolat CTA).
+- **Kapcsolat**: űrlap (név, email, üzenet, GDPR checkbox); cég e‑mail, telefonszám (ha lesz), cégnév, székhely.
+- **Admin** (előre jelzett aloldal): `/<admin>` route fenntartva; tartalom később.
+
+**Funkciók (MVP)**
+- Reszponzív navigáció (hamburger mobilon, sticky header desktopon).
+- Űrlapvalidáció (frontend: required + e‑mail forma; backend: spam‑védett endpoint).
+- SEO alapok (title/description per oldal, OG, sitemap, robots).
+- Analytics: Plausible (cookieless) vagy GA4 (cookie‑consenttel).
+
+---
+
+## 2) Nem‑funkcionális követelmények
+- **Reszponzivitás:** mobile‑first; töréspontok: 360 / 640 / 768 / 1024 / 1280+ px.
+- **Teljesítmény:** Lighthouse (mobil/desktop) ≥ 90; képek WebP/AVIF; lazy‑load; kritikus CSS minimalizálás.
+- **A11y:** WCAG 2.1 AA (fókusz, ARIA, kontraszt ≥ 4.5:1, logikus heading).
+- **Biztonság:** HTTPS, alap CSP, XSS/CSRF védelem, input szűrés a backend felé.
+- **Megfigyelhetőség:** Sentry (client) + alap logok; uptime healthcheck.
+
+---
+
+## 3) Technológiai stack
+- **Frontend:** Next.js (React + TypeScript) — SSG/SSR vegyes; App Router.
+- **UI:** Tailwind CSS + egyszerű saját komponensek (később: shadcn/ui opcionális).
+- **Űrlapok:** React Hook Form + Zod.
+- **State:** minimális local state + SWR (ha kell fetch).
+- **Teszt:** Jest + Testing Library (unit), Playwright (E2E — smoke a fő flow‑kra).
+- **CMS (opcionális később):** Strapi/Sanity; MVP‑ben statikus tartalom JSON/MDX.
+
+Projekt‑struktúra (rövid):
+```
+/src
+  /app (Next.js routes)
+  /components
+  /styles
+  /lib
+  /tests (unit + e2e cfg)
+/public
+```
+
+---
+
+## 4) Tartalom (MVP) — copy irány
+- **Hero cím** (Kezdőlap): „Megbízható web‑ és email‑szolgáltatás **személyre szabott támogatással**.”
+- **Alcím:** „Kis ügyfélkör, nagy figyelem: stabil tárhely, üzembiztos levelezés és DNS adminisztráció — gyors reakcióval.”
+- **USP bullet‑ek:** személyes ügyfélkezelés; gyors reagálás; stabil háttér; rugalmas támogatás.
+- **Webmail gomb:** „Ugrás a Webmailre”.
+- **Rólunk rövid:** mióta működtök; miért a kicsi ügyfélkör; megbízhatóság/folyamatos támogatás.
+- **Szolgáltatás dobozok:** Web Hosting / Email / DNS Admin (1–2 mondat/elem, Kapcsolat CTA).
+
+*(Megjegyzés: a végleges szöveg a review során finomhangolható.)*
+
+---
+
+## 5) Dokploy környezet — architektúra és folyamat
+
+### 5.1 Környezetek
+- **Staging**: `staging.mozdit.hu` (pl. alap auth / IP‑korlátozás, ha kell)
+- **Production**: `mozdit.hu` (www → apex redirect vagy fordítva)
+
+### 5.2 Alap komponensek
+- **Reverse proxy/ingress**: Dokploy beépített (Traefik/Nginx környezet — a dokploy stack szerint).
+- **App konténer**: Next.js app (Node 20) — SSG build + Node futtatás (vagy statikus export + Nginx).
+- **Opció**: CDN (Cloudflare) a statikus assetekhez.
+
+### 5.3 Environment változók (példa)
+- `NEXT_PUBLIC_WEBMAIL_URL=https://webmail.mozdit.hu`
+- `COMPANY_NAME=mozdIT Bt.`
+- `SITE_URL=https://mozdit.hu`
+- `ANALYTICS_PROVIDER=plausible|ga4`
+- `PLAUSIBLE_DOMAIN=mozdit.hu` (ha Plausible)
+- `GA4_ID=G-XXXXXXX` (ha GA4)
+- `CONTACT_API_URL=https://api.mozdit.hu/contact` (ha külön backend)
+
+### 5.4 Healthcheck & readiness
+- HTTP GET `/api/health` → `{status:"ok"}`
+- Staging/prod deploy csak zöld health esetén; rollback automatikus szabály (utolsó zöld image).
+
+---
+
+## 6) Docker & build
+
+### 6.1 Next.js multi‑stage Dockerfile (Node 20)
+```dockerfile
+# 1) Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* ./
+RUN npm ci --prefer-offline --no-audit --legacy-peer-deps || npm ci
+COPY . .
+RUN npm run build
+
+# 2) Run stage (Node server)
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/package.json ./package.json
+RUN npm ci --omit=dev --prefer-offline --no-audit || true
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --retries=5 CMD wget -qO- http://localhost:3000/api/health || exit 1
+CMD ["npm","start"]
+```
+*Megjegyzés:* Ha **statikus export** (SSG only) elegendő, választható Nginx runtime is.
+
+### 6.2 Dokploy app (magas szint)
+- **Repository link** + **branch per environment** (`main` → prod, `develop` → staging) vagy tag‑alapú deploy.
+- **Build & deploy**: Dockerfile alapján; port 3000; domain mapping staging/prod; env‑ek UI‑ból/secret store‑ból.
+- **Zero‑downtime**: rolling frissítés (legalább 2 replika prod‑on, ha erőforrás engedi).
+
+---
+
+## 7) CI/CD (példa: GitHub Actions)
+Workflow: **lint → unit → build → e2e (smoke, staging) → Dokploy deploy → Lighthouse check (staging) → prod release**
+
+`.github/workflows/ci.yml` (részlet):
+```yaml
+name: CI
+on:
+  push:
+    branches: ["main", "develop"]
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npm run lint && npm run test -- --ci
+      - run: npm run build
+  docker:
+    needs: build-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build & push image
+        uses: docker/build-push-action@v5
+        with:
+          push: true
+          context: .
+          tags: registry.example.com/mozdit/site:${{ github.sha }}
+  deploy-staging:
+    needs: docker
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Dokploy staging deploy
+        run: |
+          curl -X POST "$DOKPLOY_STAGING_HOOK" -H "Authorization: Bearer $DOKPLOY_TOKEN" \
+               -d '{"image":"registry.example.com/mozdit/site:${{ github.sha }}"}'
+    environment: staging
+  lighthouse:
+    needs: deploy-staging
+    runs-on: ubuntu-latest
+    steps:
+      - name: Lighthouse CI
+        run: npx @lhci/cli autorun --collect.url=https://staging.mozdit.hu
+  deploy-prod:
+    if: github.ref == 'refs/heads/main'
+    needs: lighthouse
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Dokploy prod deploy
+        run: |
+          curl -X POST "$DOKPLOY_PROD_HOOK" -H "Authorization: Bearer $DOKPLOY_TOKEN" \
+               -d '{"image":"registry.example.com/mozdit/site:${{ github.sha }}"}'
+    environment: production
+```
+*Megjegyzés:* a Dokploy‑oldali webhook/API URL és token a platform beállításától függ; ha Git integrációt használtok, a "Trigger" lépés helyett **auto‑deploy** szabály is beállítható.
+
+---
+
+## 8) Tesztelés a Dokploy stagingen
+- **Smoke E2E** (Playwright): 3 alap flow → kezdőlap betölt, Webmail link működik, Kapcsolat űrlap hibakezelés OK.
+- **Vizsgálatok**: Lighthouse (mobil & desktop), A11y ellenőrző (axe), 404/500 oldal viselkedés.
+- **Megfigyelés**: Sentry DSN kapcsolva; health endpoint figyelése.
+
+---
+
+## 9) Biztonság & adatvédelem
+- HTTPS (Let’s Encrypt / Dokploy integráció), HSTS.
+- **CSP** baseline (script‑src 'self' + szükséges 3rd party); **Referrer‑Policy**, **X‑Frame‑Options** (SAMEORIGIN), **X‑Content‑Type‑Options**.
+- **GDPR**: cookie banner ha GA4; Plausible esetén banner elhagyható.
+- Kapcsolat űrlap: captcha/light rate‑limit, backend input validáció, e‑mail küldés queue‑val (ha szükséges).
+
+---
+
+## 10) Rollback, backup, verziózás
+- **Release tag** (semver) + image tag; Dokploy‑ban korábbi image visszagörgetés.
+- **Konfig backup**: env‑ek és Dokploy app export; infra‑as‑code (Dockerfile, workflow‑k) GIT‑ben.
+
+---
+
+## 11) Elfogadási kritériumok (MVP)
+- Kezdőlap, Rólunk, Szolgáltatások, Kapcsolat elérhető és reszponzív.
+- Webmail link jól működik (új lapon, nofollow opcionális).
+- Lighthouse ≥ 90 minden fő mérőszámon stagingen.
+- Űrlap hibák/fókuszállapotok a11y‑konformak.
+- CI pipeline zöld, staging deploy automatikus; prod deploy csak zöld staging után.
+
+---
+
+## 12) Kezdő feladatlista (ticket sablonok)
+1. **Repo & Next.js bootstrap** — *Acceptance*: app indul dev módban; TS, ESLint, Prettier beállítva.
+2. **Tailwind + alap layout** — *Acceptance*: reszponzív header/footer; tipográfia, színek.
+3. **Kezdőlap (Hero + USP + Webmail CTA)** — *Acceptance*: 1s alatt festődik mobilon; link működik.
+4. **Rólunk oldal** — *Acceptance*: heading‑hierarchia helyes; szövegek MDX‑ből tölthetők.
+5. **Szolgáltatások oldal** — *Acceptance*: 3 doboz + CTA → Kapcsolat.
+6. **Kapcsolat űrlap + API stub** — *Acceptance*: validáció, hibák; egyszerű spam‑védelem.
+7. **/api/health endpoint** — *Acceptance*: `{status:"ok"}` JSON.
+8. **Dockerfile + Dokploy staging app** — *Acceptance*: buildel, deployol, domain él.
+9. **CI (lint, unit) + Staging deploy trigger** — *Acceptance*: PR‑re fut; stagingre pushol.
+10. **Playwright smoke E2E + Lighthouse CI** — *Acceptance*: fut stagingen, riport mentve.
+11. **Prod app + domain + HTTPS** — *Acceptance*: élő site; automatikus HTTPS; monitoring bekapcsolva.
+
+---
+
+## 13) Későbbi bővítések
+- Blog/Újdonságok; többnyelvűség; admin aloldal funkciói; CDN cache; képgenerálás; CMS integráció.
+
+---
+
+*Megjegyzés:* A végleges Dokploy beállítások (webhook/API, auto‑deploy, replika szám, storage) a rendelkezésre álló szerver erőforrásoktól és a Dokploy verziójától függően finomhangolandók.
+