Architekturális dokumentáció

Áttekintés fejlesztőknek/technikai érdeklődőknek — a repo saját belső dokumentációja (PROJECT_CONTEXT.md, DEPLOYMENT.md) részletesebb, de nem publikus.

Stack

Backend: NestJS 11 (TypeScript), Prisma 6 ORM, PostgreSQL 16
Frontend: szerver-renderelt HTML/vanilla JS template literal-ok — nincs build lépés, nincs SPA-framework (React/Vue/Angular)
Auth: JWT (Bearer token), bcrypt jelszó-hash
PDF-generálás: Puppeteer (headless Chromium) — a riport HTML-sablonból renderel, on-demand, nem perzisztált fájlként
Fájl-feltöltés: Multer, perzisztens tárhelyre (Docker volume)
Export/import: ExcelJS (XLSX)
Hosting: önálló szerver, Docker-alapú (Coolify), Nixpacks build, Node 22

Modulok

Modul	Felelősség
auth	Bejelentkezés, JWT kiadás/validálás, szerepkör-alapú jogosultság (ADMIN/SUPER_ADMIN/PARTNER/FIELD_UPLOADER)
partners	Partner (megrendelő) CRUD, saját bejelentkezés generálása, "segéd" (FIELD_UPLOADER) felhasználók létrehozása/listázása
products	Terméktörzs CRUD + XLSX import
events	Esemény életciklus (DRAFT→ACTIVE→CLOSED), QR-kód generálás (fő esemény- és per-segéd QR-token), kiosztott termékek
survey	Anonim kérdőív-beküldés és -listázás (fő vagy segéd QR-tokenből feloldva)
impact	A 6 hatás-mutató kiszámítása egy eseményre
reports	Mutató-pillanatkép rögzítése/verziózása + PDF-renderelés
export	XLSX/CSV exportok (események+mutatók, kérdőív-válaszok, terméktörzs)
uploads	Kép-feltöltés (pl. partner logó)
settings	Kulcs-érték konfiguráció (márka-paletta, CO2e-baseline stb.)
chat	Statikus FAQ + AI-alapú (Gemini) súgó-widget
feedback	Bejelentkezett felhasználóktól érkező szöveges visszajelzés — emailben (MailService/SMTP) és admin-listaként is
admin-ui / docs	Szerver-renderelt admin/partner/segéd felület és publikus dokumentáció

Adatmodell (vázlat)

Partner 1—N Event N—N Product (a kapcsolótábla: EventProduct, kiosztott/elfogyott mennyiséggel) · Event 1—N SurveyResponse (anonim) · Event 1—N Report (verziózott mutató-pillanatkép) · Event 1—N EventHelper (egy "segéd"/FIELD_UPLOADER felhasználó hozzárendelése, saját QR-tokennel — a SurveyResponse opcionálisan ide is hivatkozik, hogy visszakövethető legyen, melyik QR-kódon jött be a válasz) · User (szerepkör: ADMIN/SUPER_ADMIN/PARTNER/ FIELD_UPLOADER) · Feedback (a bejelentkezett felhasználóktól érkező visszajelzés, opcionális User hivatkozással) · Setting (kulcs-érték konfiguráció).

Minden fő entitáson (Partner/Product/Event) soft delete van (archivedAt mező) — nincs kemény törlés, az adat korlátlan ideig megőrzött marad.

A hatás-mutatók (DRAFT állapotú képletek)

Az ImpactService egy esemény kiosztott/elfogyott termékei és kérdőív-válaszai alapján számolja ki mind a 6 mutatót (Snack Replacement, Upcycled arány, Food Waste Reduced, Inkluzív hozzáférés, Feedback Score, CO2e-becslés). A paraméterek (pl. CO2e baseline) a Setting táblából jönnek, nem kódba égetve — így a végleges módszertan (workshop utáni) kódmódosítás nélkül finomhangolható. Részletek: /docs.

Biztonság és adatvédelem

A SurveyResponse modellen SOSEM tárolunk IP-t, user agentet vagy bármilyen személyes azonosítót — a kérdőív teljesen anonim.
Bejelentkezés JWT-vel, bcrypt-tel hash-elt jelszóval; minden végpont szerepkör-alapúan (RolesGuard) szűkíti a hozzáférést — PARTNER csak a saját, FIELD_UPLOADER csak a hozzá rendelt eseményekhez fér hozzá, riportot/exportot egyáltalán nem ér el.
A kérdőív-QR-kép végpontok (/events/:id/qr.png és társai) szándékosan publikusak, mert csak a nyilvános kérdőív-URL-t kódolják — minden más esemény-végpont auth-ot igényel.
A publikus végpontok (kérdőív-beküldés) rate-limitelve vannak.

Forráskód

A forráskód privát repóban él, nem publikusan elérhető. Ez az oldal csak az architektúra áttekintésére szolgál.