ATESZ Event Planner – server.js technikai dokumentáció

Dokumentáció verzió:

A lenyíló lista segítségével elkülöníthető az eredeti egyfájlos backend dokumentáció (v1) és a későbbi refaktorált backend szerkezetet bemutató dokumentáció (v2).

v1 dokumentáció

Dokumentáció célja

Ez az oldal a rendszer backend központját jelentő server.js működését írja le üzleti, technikai és karbantartási nézőpontból. A cél, hogy egyértelműen látszódjon: melyik route mire szolgál, milyen helper-ek támogatják, milyen fájlokat hoz létre, hogyan épül fel a planner és a quote workflow, valamint milyen pontokon érdemes később refaktorálni.

Planner session mentés

Quote / CRM generálás

Dashboard summary

Calendar API

Upload / config route-ok

PDF / ICS generálás

Index rebuild

1. Rendszeráttekintés

A server.js egy monolitikus Express backend, amely a teljes planner ökoszisztéma szerveroldali központja. Ez a fájl egyszerre kezeli a route-okat, a fájlalapú persistence-et, a template bootstrapet, a PDF generálást, az ICS exportot, az indexelést, a dashboard aggregációt és a statisztikai összesítéseket.

Fő üzleti entitások

A rendszer két fő entitás köré épül: a planner session és a quote. A planner session teljes rendezvényadatlapot jelent, a quote pedig külön életciklusú ajánlati dokumentum.

Technikai karakter

A rendszer adatbázis helyett fájlrendszerre épül. JSON rekordok, PDF dokumentumok, ICS állományok és indexfájlok alkotják a teljes storage réteget.

A jelenlegi v1 backend gyorsan fejleszthető és egyszerűen telepíthető, de hosszabb távon indokolt a route, service, storage és PDF logika külön modulokra bontása.

2. Rendszertérkép

Ez a blokk magas szinten mutatja meg, milyen bemeneti felületek, milyen backend logikai egységek és milyen tárolási pontok kapcsolódnak egymáshoz.

Frontend belépési pontok

index.html – planner wizard
crm.html – quote és follow-up
dashboard.html – admin dashboard
calendar.html – havi eseménynaptár
dj-view.html – preview nézet

Backend logikai zónák

planner mentés és visszatöltés
quote generálás és follow-up
helyszín- és template-kezelés
dashboard aggregáció
calendar aggregáció
statisztikai gyűjtés

Tárolási pontok

/data – planner JSON / PDF / ICS
/data/_index.json – planner index
/data/quotes – quote JSON / PDF
/data/quotes/_quotes_index.json – quote index
/uploads – képek, aláírások, jegyzetek

Konfigurációs pontok

/public/venues.json
/public/templates/index.json
/public/templates/*.json
payment-transfer.json
DASHBOARD_MASTER_PASSWORD

3. Fájlszerkezet

ROOT/
├─ public/
│  ├─ main.html
│  ├─ venues.json
│  ├─ templates/
│  │  ├─ index.json
│  │  ├─ wedding_classic.json
│  │  ├─ wedding_premium_show.json
│  │  ├─ corporate_gala.json
│  │  ├─ prom_standard.json
│  │  ├─ ball_classic.json
│  │  └─ payment-transfer.json
│  └─ fonts/
├─ data/
│  ├─ _index.json
│  ├─ _counters.json
│  ├─ <stamp>.json
│  ├─ <stamp>.pdf
│  ├─ <stamp>.ics
│  └─ quotes/
│     ├─ _quotes_index.json
│     ├─ <quote-stamp>.json
│     └─ <quote-stamp>.pdf
└─ uploads/
   └─ feltöltött képek

Planner storage

Egy planner sessionhez tipikusan három fájl jön létre: JSON, PDF, ICS.

Quote storage

Egy quote rekordhoz jellemzően két fájl tartozik: JSON és PDF.

4. Indítás és inicializálás

A backend induláskor több bootstrap lépést hajt végre, hogy a szükséges fájlszerkezetek és alapkonfigurációk rendelkezésre álljanak.

1. Könyvtárak létrehozása DATA_DIR, UPLOADS_DIR, TEMPLATES_DIR, QUOTES_DIR

2. Venue file ellenőrzése Ha hiányzik, létrejön a default helyszínlista.

3. Template file-ok ellenőrzése Ha hiányzik a template index, bootstrapelődik az egész template készlet.

4. Payment transfer config ellenőrzése Ha hiányzik, létrejön az alap bankszámla konfiguráció.

5. Planner index ellenőrzése Ha üres, a backend újraépíti a fájlrendszerből.

5. Middleware és app setup

Middleware-ek

express.json({ limit: "12mb" })
express.urlencoded({ extended: true })
express.static(PUBLIC_DIR, { index:false })
app.use("/data", express.static(DATA_DIR))
app.use("/uploads", express.static(UPLOADS_DIR))

Megjegyzés

A /data és /uploads közvetlen publikálása egyszerű frontend működést ad, de biztonsági szempontból érzékeny pont.

6. Helper függvények

A server.js nagyszámú helper függvényt tartalmaz, amelyek a logika gerincét adják.

Normalizáló és parse helper-ek

safeSlug()
normalizeDate()
normalizeText()
normalizeArray()
toIntOrNull()
toFloatOrZero()
toBool()
formatMoney()

Fájl és storage helper-ek

fileStamp()
writeJsonAtomic()
readJson()
replaceFileAtomic()
safeUnlink()
loadIndex()
saveIndexAtomic()

Quote helper-ek

loadCounters()
saveCounters()
nextQuoteNumber()
normalizeQuotePayload()
makeQuoteStamp()
loadQuoteIndex()
saveQuoteIndex()

PDF / timeline helper-ek

buildAutoTimeline()
generateICS()
drawHeader()
drawTable()
kvInline()
eventTypeLabelHu()
paymentStatusLabelHu()

7. Venue kezelés

A venue rendszer a public/venues.json fájlra épül.

Kapcsolódó függvények

ensureVenuesFile()
loadVenuesFile()
saveVenuesFile()
addVenueToFile()

Működés

Az új helyszín mentése duplikációellenőrzéssel történik, majd a lista magyar rendezés szerint visszaírásra kerül.

8. Template bootstrap

A template rendszer első induláskor automatikusan létrehozza az alap eseménysablonokat.

wedding_classic

wedding_premium_show

corporate_gala

prom_standard

ball_classic

A sablonok nem végleges rekordok, hanem előtöltési konfigurációk: időpontok, technikai szintek, effect kapcsolók és fizetési módok alapállapotát adják.

9. Payment transfer konfiguráció

Az átutalási adatok külön fájlban élnek, és több frontend / PDF folyamat támaszkodik rájuk.

{
  "bankAccount": "11712345-12345678-12345678",
  "accountOwner": "Tarján Attila",
  "bankName": "CIB Bank Zrt"
}

10. Timeline és ICS logika

A backend képes automatikus menetrendet generálni, illetve importálható naptárfájlt készíteni.

Wedding logika ceremonyStart vagy guestArrivalTime alapján számol vacsora, torta, éjféli keringő, menyasszonytánc időket

Generic event logika evGuestArrivalTime alapján számol opening, dinner, award, presentation, networking, afterparty időket

ICS export VEVENT alapú állományt ír ki, a zárás automatikusan másnapra eshet

11. Planner index rendszer

A planner index célja a gyors listázás, keresés és dashboard / calendar aggregáció támogatása.

Fő függvények

makeIndexEntryFromRecord()
rebuildIndexFromFiles()
upsertIndexEntry()
filterIndexItems()
findConflictsByDate()

Megjegyzés

A rendszer nem részleges index update-re, hanem rebuild + write mintára épül.

12. Quote index rendszer

A quote index a quote lista, accepted quote import és dashboard quote blokk alapja.

Fő függvények

makeQuoteIndexEntry()
rebuildQuoteIndexFromFiles()
upsertQuoteIndexEntry()

Quote számláló

A quote sorszámozás a _counters.json fájlban tárolt éves számlálóra épül.

13. PDF generálási rendszer

A backend két nagy PDF generálási útvonallal rendelkezik: planner PDF és quote PDF.

Planner PDF

alapadatok
kapcsolattartás
zenei igények
esemény-specifikus menetrend
pénzügyek
technika
jóváhagyás
jegyzet képek

Quote PDF

ajánlati metaadatok
megrendelő / esemény adatok
szolgáltatási időintervallum
ajánlati tartalom
pénzügyi összesítés
follow-up esetén számla és utókövetés

14. Planner API

POST /api/sessions

Planner mentés, PDF és ICS generálás

A planner fő mentési route-ja. Validál, JSON-t ír, PDF-et és ICS-t generál, majd indexet frissít és konfliktusellenőrzést futtat.

GET /api/sessions

Planner lista és szűrés

Query paraméterek alapján planner indexet szűr, és gyors listaadatokat ad vissza.

GET /api/session/:stamp

Egy planner rekord teljes betöltése

DELETE /api/session/:stamp

Planner rekord törlése

15. Quote / CRM API

POST /api/quotes/generate

Ajánlat létrehozása és PDF generálás

GET /api/quotes

Quote lista lekérése

GET /api/quote/:stamp

Egy quote rekord lekérése

DELETE /api/quote/:stamp

Quote törlése

GET /api/planner-accepted-quotes

Accepted quote lista plannerhez

GET /api/planner-accepted-quote/:stamp

Accepted quote részletes betöltése

16. Segédvégpontok

GET/api/venues

Venue lista lekérése

POST/api/venues

Új venue mentése

POST/api/upload

Képfeltöltés

GET/api/conflicts

Dátumütközés keresés

POST/api/autotimeline

Automatikus timeline számítás

GET/api/payment-transfer-config

Átutalási konfiguráció lekérése

17. Dashboard és calendar

GET/api/dashboard-summary

Dashboard aggregált összesítés

GET/api/calendar

Havi naptáradatok

POST/api/auth/dashboard

Dashboard auth

POST/api/auth/price-view

DJ price-view auth

18. Statisztikai logika

A /api/stats route a planner indexből és rekordokból gyakorisági toplistákat készít.

Gyűjtött mutatók

top genres
top do not play tokenek
dinner frequency
cake frequency
venue frequency

További bontások

status frequency
paid frequency
dj tech frequency
totalSessions

19. Fájl-létrejövési mátrix

Route	Művelet	Érintett fájlok
`POST /api/sessions`	create/update	`/data/<stamp>.json`, `.pdf`, `.ics`, `_index.json`
`DELETE /api/session/:stamp`	delete	`/data/<stamp>.json`, `.pdf`, `.ics`, `_index.json`
`POST /api/quotes/generate`	create/update	`/data/quotes/<stamp>.json`, `.pdf`, `_quotes_index.json`, `_counters.json`
`DELETE /api/quote/:stamp`	delete	`/data/quotes/<stamp>.json`, `.pdf`, `_quotes_index.json`
`POST /api/upload`	create	`/uploads/<generated_file>`

20. Hibakezelési stratégia

Tipikus státuszkódok

200 – sikeres válasz
400 – hibás bemenet / validáció
403 – üzleti tiltás
404 – nem található rekord
500 – belső szerverhiba

Jellemző hibatípusok

hiányzó kötelező mező
PDF generálási hiba
sérült JSON fájl
fájlrendszer jogosultsági probléma
nem accepted quote betöltés

21. Fő működési folyamatok

Planner mentés frontend payload → /api/sessions → JSON → PDF → ICS → index update

Quote generálás CRM payload → /api/quotes/generate → quote JSON → quote PDF → quote index

Dashboard betöltés auth → /api/dashboard-summary → aggregáció → dashboard render

Calendar betöltés /api/calendar?month=... → havi rács + napi eseménylista

22. Ismert korlátok

Jelenlegi korlátok

monolitikus backend fájl
nincs adatbázis
nincs role-based auth
index rebuild költséges lehet nagy állománynál
publikus file storage útvonalak

Karbantarthatósági pontok

PDF logika túl nagy
route és service logika keveredik
storage logika nincs külön rétegben
validáció nincs központi sémaalapra húzva

23. Refaktor megjegyzések

A backend refaktor ideális sorrendje:

1. Storage réteg kiválasztása JSON / PDF / ICS fájlműveletek külön modulba

2. Route réteg bontása planner, quotes, dashboard, calendar, support route külön fájlokba

3. PDF builder szétválasztása planner PDF és quote PDF külön service-be

4. Sémaalapú validáció Zod / Joi vagy egyedi validator réteg

A frontend már modulárisabb irányba indult, ezért a backend refaktor következő logikus lépés.

v2 dokumentáció

Dokumentáció célja

Ez az oldal a refaktorált backend szerkezetet dokumentálja. A V2 célja nem új rendszer bevezetése volt, hanem a korábbi monolitikus server.js logikájának biztonságos, frontend-kompatibilis szétbontása úgy, hogy a futtatás, az API-k, a fájlstruktúra, a PDF / ICS mellékhatások és a mentett adatok változatlanul megmaradjanak.

Launcher + app bootstrap

Planner domain

Quote / CRM domain

Dashboard

Calendar

Auth

Support services

Storage

Utilities

1. V2 rendszeráttekintés

A V2 backend a wedding-planner-dj rendszer refaktorált szerveroldali architektúrája. A cél nem új működés bevezetése volt, hanem a korábbi, monolitikus server.js logikájának moduláris, domain-alapú szétbontása úgy, hogy a futtatás, az API-k, az adatstruktúrák, a fájlkimenetek és a frontend kompatibilitás teljes egészében megmaradjon.

A V1 rendszerben minden jelentős backend folyamat egyetlen fájlban helyezkedett el: route kezelés, planner session mentés, quote generálás, indexek újraépítése, conflict check, upload, dashboard summary, calendar aggregáció, statisztika, PDF generálás, ICS export, valamint a fájlkezelési helper-ek. Ez gyors indulást tett lehetővé, de a projekt növekedésével a karbantarthatóság és az olvashatóság jelentősen romlott.

A V2 refaktor során a rendszer működése változatlan maradt, de a felelősségi körök külön rétegekbe kerültek: route, service, storage, utility és config modulokra. Ezzel a backend szerkezete összhangba került a már korábban refaktorált frontend JS domain-bontásával is.

Mi változatlan?

API endpoint URL-ek és HTTP method-ok
request body és response shape
planner és quote fájlstruktúra
PDF és ICS generálás eredménye
quote sorszámozási logika
projekt indítása a gyökér server.js fájllal

Mi változott?

route-ok külön domain fájlokba kerültek
üzleti logika service modulokba került
storage műveletek külön rétegbe kerültek
általános helper-ek util modulokra bontódtak
launcher és Express bootstrap különvált

Refaktor alapelv: a V2 nem “új backend”, hanem a V1 működésének biztonságos, kompatibilis újraszervezése. A külső szerződés változatlan, a belső szerkezet rendezettebb.

2. V2 rendszertérkép

A backend továbbra is ugyanazokat a frontend oldalakat szolgálja ki, mint a V1, de a szerveroldali logika már domainenként külön modulokra oszlik.

Frontend belépési pontok

index.html – planner wizard
crm.html – quote és follow-up
dashboard.html – admin dashboard
calendar.html – havi calendar
dj-view.html – preview / price-view

Backend domain zónák

planner
quotes / CRM
dashboard
calendar
auth
support / shared

Fizikai storage pontok

/data – planner JSON / PDF / ICS
/data/_index.json – planner index
/data/quotes – quote JSON / PDF
/data/quotes/_quotes_index.json – quote index
/uploads – képek, aláírások, jegyzetek

Refaktorált logikai pontok

server/routes – HTTP endpointok
server/services – domain logika
server/storage – fájlműveletek
server/utils – közös helper-ek
server/config – útvonalak és konstansok

3. Fájlszerkezet

ROOT/
├─ public/
│  ├─ main.html
│  ├─ venues.json
│  ├─ templates/
│  │  ├─ index.json
│  │  ├─ wedding_classic.json
│  │  ├─ wedding_premium_show.json
│  │  ├─ corporate_gala.json
│  │  ├─ prom_standard.json
│  │  ├─ ball_classic.json
│  │  └─ payment-transfer.json
│  └─ fonts/
├─ data/
│  ├─ _index.json
│  ├─ _counters.json
│  ├─ <stamp>.json
│  ├─ <stamp>.pdf
│  ├─ <stamp>.ics
│  └─ quotes/
│     ├─ _quotes_index.json
│     ├─ <quote-stamp>.json
│     └─ <quote-stamp>.pdf
├─ uploads/
│  └─ feltöltött képek
├─ server.js
└─ server/
   ├─ app.js
   ├─ config/
   │  ├─ paths.js
   │  └─ constants.js
   ├─ routes/
   │  ├─ planner.routes.js
   │  ├─ quotes.routes.js
   │  ├─ dashboard.routes.js
   │  ├─ calendar.routes.js
   │  ├─ auth.routes.js
   │  └─ support.routes.js
   ├─ services/
   │  ├─ planner/
   │  ├─ quotes/
   │  ├─ dashboard/
   │  ├─ calendar/
   │  ├─ stats/
   │  └─ support/
   ├─ storage/
   │  ├─ json-store.js
   │  ├─ atomic-write.js
   │  └─ file-store.js
   └─ utils/
      ├─ normalize.js
      ├─ money.js
      ├─ date.js
      ├─ time.js
      └─ text.js

A projektgyökérben maradt minden olyan elem, amelyhez a frontend vagy az üzemeltetés közvetlenül kötődik. A server/ könyvtár kizárólag a backend kód új, logikai szerkezete.

4. Szerver indítása és futási modell

A refaktor után is a gyökérbeli server.js a belépési pont. Ez a fájl launcher szerepet tölt be, a tényleges Express alkalmazást a server/app.js állítja össze.

node server.js
   ↓
root/server.js
   ↓
server/app.js
   ↓
routes/*
   ↓
services/*
   ↓
storage/* + utils/*

1. launcher A root server.js beolvassa a konfigurált portot és elindítja az appot.

2. Express bootstrap Az app.js példányosítja az Express-t, middleware-eket állít be, statikus útvonalakat publikál és mountolja a route-okat.

3. Domain route kezelés A route modulok a requesteket domainhez delegálják.

Ez a modell biztosítja, hogy a projekt üzemeltetési folyamata változatlan maradjon, miközben a kód már nem egy monolitikus szerverfájlban él.

5. Config réteg

A config réteg feladata a fizikai útvonalak és az állandó értékek központosítása. Ez csökkenti a szórt konstanshasználatot és biztosítja, hogy minden domain modul ugyanazokra a stabil hivatkozásokra épüljön.

paths.js

A projekt abszolút útvonalait kezeli: ROOT, PUBLIC_DIR, DATA_DIR, UPLOADS_DIR, indexfájlok, quote könyvtár és template konfigurációs fájlok.

constants.js

A port, auth jelszó és egyéb állandó működési paraméterek központi definíciója. Ez megkönnyíti a későbbi finomhangolást és csökkenti a hardcoded értékek számát.

A config réteg bevezetése különösen azért fontos, mert a refaktor után a backend modulok már nem a projektgyökérből, hanem egymástól elkülönülten futnak, és közös útvonaldefinícióra van szükségük.

6. Middleware és app setup

Az app.js feladata az Express alapkonfiguráció és a middleware-ek bekötése. Itt történik a JSON body kezelés, az URL encoded body kezelés és a statikus mappák publikálása is.

Használt middleware-ek

express.json(...)
express.urlencoded(...)
express.static(PUBLIC_DIR)
express.static(DATA_DIR)
express.static(UPLOADS_DIR)

Miért az app.js-ben vannak?

Mert ezek nem üzleti folyamatok, hanem az Express alkalmazás globális infrastruktúráját alkotják. A middleware-ek domainfüggetlenek, ezért nem route- vagy service-feladatok.

A /data és /uploads publikus publikálása a frontend működésének része, ezért a refaktor során nem változott meg.

7. Route réteg részletesen

A route réteg a HTTP endpointok belépési pontja. A route fájlok kizárólag request fogadással, paraméterek kiolvasásával, service hívással és response formázással foglalkoznak. A V2-ben a route-ok domain szerint külön fájlokba kerültek.

Route fájl	Kapcsolódó endpointok	Felelősség
planner.routes.js	`POST /api/sessions` `GET /api/sessions` `GET /api/session/:stamp` `DELETE /api/session/:stamp` `GET /api/conflicts` `POST /api/autotimeline` `GET /api/planner-accepted-quotes` `GET /api/planner-accepted-quote/:stamp`	planner domain
quotes.routes.js	`POST /api/quotes/generate` `GET /api/quotes` `GET /api/quote/:stamp` `DELETE /api/quote/:stamp`	quote / CRM domain
dashboard.routes.js	`GET /api/dashboard-summary`	dashboard aggregáció
calendar.routes.js	`GET /api/calendar`	calendar aggregáció
auth.routes.js	`POST /api/auth/dashboard` `POST /api/auth/price-view`	dashboard és DJ preview auth
support.routes.js	`GET /api/venues` `POST /api/venues` `POST /api/upload` `GET /api/payment-transfer-config` `GET /api/stats` `GET /`	közös support és fallback route-ok

A route rétegben több tudatosan külön hagyott endpoint is található. Ezek szerkezetileg hasonlónak tűnhetnek, de üzletileg külön frontend folyamatokat szolgálnak ki, ezért nem lettek összevonva.

8. Service réteg részletesen

A service réteg hordozza a rendszer üzleti logikáját. A route-ok innen hívják meg a tényleges feldolgozási folyamatokat. A V1-ben ezek a folyamatok egyetlen szerverfájlban voltak keveredve, a V2-ben domain szerint külön service modulokba kerültek.

Planner service-ek

planner-save.service.js – mentési főfolyamat
planner-read.service.js – lista, rekord, delete
planner-index.service.js – index build / upsert / filter
planner-conflict.service.js – ütközésvizsgálat
planner-accepted-quotes.service.js – accepted quote import
planner-pdf.service.js – planner PDF
planner-ics.service.js – ICS export

Quote service-ek

quote-save.service.js – quote mentés
quote-read.service.js – quote lista / rekord / delete
quote-index.service.js – quote index
quote-pdf.service.js – quote PDF
quote-number.service.js – AJ sorszámozás

Dashboard / calendar / stats

dashboard-summary.service.js
calendar.service.js
stats.service.js

Support service-ek

venue.service.js
template.service.js
payment-transfer.service.js
upload.service.js

A service-ekre bontás elsődleges célja az volt, hogy a domain folyamatok — például planner mentés vagy quote generálás — már ne route, PDF helper és I/O kód keverékében legyenek jelen.

9. Planner rendszer

A planner domain kezeli az események mentését, listázását, törlését, exportját és konfliktusvizsgálatát. Ez a backend legösszetettebb üzleti területe.

Planner rekord fő tartalmi területei

alapadatok (dátum, pár neve, helyszín)
kapcsolattartási adatok
zenei igények és tiltólista
esemény-specifikus menetrend
technikai információk
pénzügyi mezők
jegyzetek, attachmentek és aláírás

A planner rekord formátuma és fájlelhelyezése a V2-ben is megegyezik a V1 rendszerrel. Ez biztosítja a régi adatok zavartalan továbbélését.

10. Planner mentési folyamat

A planner mentés a rendszer egyik legfontosabb backend folyamata. A V2-ben ennek fő vezérlője a planner-save.service.js.

1. Request fogadás A planner.routes.js fogadja a POST /api/sessions hívást.

2. Validáció és normalizálás A save service ellenőrzi a kötelező mezőket, kezeli a signature / attachment mezőket, és ha szükséges, auto timeline adatokat tölt.

3. Session rekord összeállítása A rekord a V1-ben használt JSON struktúrával jön létre, hogy a frontend visszatöltés és a meglévő indexlogika kompatibilis maradjon.

4. JSON mentés A rekord a data/<stamp>.json fájlba kerül.

5. PDF és ICS export A planner PDF és az ICS export külön service-ekben készül el.

6. Index frissítés és conflict check Az index update után a rendszer visszaadja az adott napra eső esetleges további eseményeket is.

A V2 mentési folyamat lépéseiben megegyezik a V1 működésével; a fő különbség az, hogy a felelősségek most már külön service-ek között oszlanak meg.

11. Planner lista, rekordlekérés és törlés

A planner read műveletek a planner rekordok gyors elérését biztosítják listázás, részletes betöltés és törlés esetén.

Planner lista

A GET /api/sessions a planner indexből olvassa ki a rekordok gyors metaadatait, és query paraméterek alapján szűri őket.

Egy planner rekord

A GET /api/session/:stamp a teljes JSON rekordot tölti be és adja vissza a frontendnek.

Törlés

A DELETE /api/session/:stamp törli a JSON, PDF és ICS fájlokat, majd frissíti az indexet. A V2-ben a törlési logika külön read / index service-ekre támaszkodik.

12. Planner index rendszer

A planner index a gyors listázás, a dashboard és a calendar aggregáció alapja. Ez a rendszer nem a teljes rekordokkal dolgozik, hanem egy külön indexfájlban tárolt metaadat-struktúrával.

Index tartalma

stamp
eventDate
coupleName
venue
status
isPaid
djTechLevel
timeline metaadatok

Index service feladatai

index fájl beolvasása
index újraépítése fájlokból
egyetlen rekord upsert
lista szűrése query paraméterek szerint

A planner index és a quote index tudatosan külön maradtak, mert bár szerkezetileg hasonlóak, üzletileg eltérő mezőket és életciklust kezelnek.

13. Conflict check logika

A conflict check célja, hogy a planner mentésekor a rendszer vissza tudja adni, ha ugyanarra a napra már létezik másik esemény.

Működés

A GET /api/conflicts és a planner mentési folyamat is a conflict service-re támaszkodik. A rendszer a planner index alapján összeveti az adott dátumot a többi rekord dátumával, és opcionálisan kizárhat egy saját stamp-et.

A conflict check nem blokkoló mechanizmus, hanem figyelmeztető és visszajelző funkció a frontend számára.

14. Planner PDF rendszer

A planner PDF a teljes eseményadatlap nyomtatható és archiválható formája. A V2-ben a renderelési logika külön service-be került, de a dokumentum szerkezete változatlan maradt.

Planner PDF blokkok

alapadatok
kapcsolattartás
zenei igények
esemény-specifikus menetrend
pénzügyek
technikai adatok
jegyzetek
jóváhagyás és aláírás
csatolt képek

Miért külön service?

Mert a PDF builder jelentős mennyiségű megjelenítési logikát és layout helper-t tartalmaz, amely nem route- és nem storage-szintű felelősség.

15. Timeline és ICS logika

A planner domain két időalapú segédfunkciót is tartalmaz: az auto timeline számítást és az ICS exportot.

Auto timeline A rendszer az eseménytípus és bizonyos kiinduló időpontok alapján automatikusan kitölt ajánlott menetrendi mezőket.

Wedding timeline A ceremónia vagy vendégvárás idejéből számít vacsora, torta, éjféli keringő és menyasszonytánc időpontokat.

Generic event timeline Az evGuestArrivalTime alapján számol opening, dinner, award, presentation, networking és afterparty mezőket.

ICS export A planner rekordból importálható VEVENT állomány készül.

Az auto timeline és az ICS export logikailag nem ugyanaz: az egyik a kitöltést segíti, a másik export fájlt hoz létre. Ezért külön service-be kerültek.

16. Planner API referencia

POST /api/sessions

planner mentés

Planner rekord mentése, PDF és ICS generálás, index frissítés és conflict check.

{
  "eventType": "wedding",
  "coupleName": "Kovács Anna és Szabó Péter",
  "eventDate": "2026-07-18",
  "venue": "Szeged - Kastélykert Birtok",
  "guestArrivalTime": "17:00",
  "dinnerTime": "19:00",
  "attachments": [],
  "autoTimeline": true
}

{
  "ok": true,
  "id": "uuid",
  "stamp": "kovacs_anna_es_szabo_peter_2026-07-18",
  "json": "/data/....json",
  "pdf": "/data/....pdf",
  "ics": "/data/....ics",
  "conflicts": []
}

GET /api/sessions

planner lista és szűrés

Query paraméterek alapján a planner indexből szűrt listát ad vissza.

/api/sessions?q=anna&status=szerződött&dateFrom=2026-01-01&dateTo=2026-12-31

GET /api/session/:stamp

teljes rekord betöltése

A planner teljes JSON rekordját adja vissza.

DELETE /api/session/:stamp

rekord törlése

Törli a JSON, PDF és ICS fájlt, majd indexet frissít.

GET /api/conflicts

dátumütközés keresése

/api/conflicts?eventDate=2026-07-18&excludeStamp=kovacs_anna...

POST /api/autotimeline

automatikus timeline számítás

{
  "eventType": "wedding",
  "ceremonyStart": "15:00",
  "midnightWaltz": true,
  "brideDance": true
}

{
  "ok": true,
  "generated": {
    "guestArrivalTime": "17:00",
    "dinnerTime": "18:00",
    "cakeTime": "21:30",
    "midnightWaltzTime": "00:00",
    "brideDanceTime": "01:00"
  }
}

17. Quote / CRM rendszer

A quote domain a CRM oldali ajánlatkészítést és follow-up folyamatot szolgálja ki. Bár a plannerhez hasonlóan JSON + PDF állományokra épül, üzletileg külön entitást kezel.

Quote domain célja

Árajánlat létrehozása, nyomon követése, státuszkezelése és a planner rendszerrel való kapcsolata.

Miért külön domain?

Mert a quote rekordok nem azonosak a planner session rekordokkal: külön életciklusuk, külön indexük és külön PDF logikájuk van.

18. Quote mentési folyamat

A quote mentés a CRM egyik fő backend folyamata. A save service feladata a quote payload normalizálása, a sorszámképzés és a storage folyamat vezérlése.

1. Request fogadás A quotes.routes.js fogadja a POST /api/quotes/generate hívást.

2. Quote payload normalizálás A rendszer kiszámolja a base, extras, discount és total értékeket, valamint előállítja a default validitási adatokat.

3. Quote szám generálás Ha nincs explicit quote szám, a quote-number service előállítja az éves AJ sorszámot.

4. JSON és PDF létrehozás A quote rekord JSON-ként mentődik, majd a quote PDF service létrehozza a dokumentumot.

5. Quote index frissítés A quote-index service biztosítja a gyors kereshető listázást és dashboard statisztikai integrációt.

19. Quote index és quote számozás

Quote index

A quote index a quote rekordok gyors listázására, státusz szerinti szűrésére, accepted quote importjára és dashboard quote összesítésekre szolgál.

Quote számozás

A quote number service a _counters.json alapján kezeli az éves AJ sorszámozást. Ez domain-specifikus üzleti szabály, ezért nem általános util vagy storage helper.

20. Quote PDF rendszer

A quote PDF builder a quote domain vizuális dokumentumrétege. A planner PDF-től külön service-ben található, mert eltérő adatstruktúrát és eltérő üzleti célt szolgál.

Fő blokkok

ajánlati metaadatok
megrendelő / esemény adatok
szolgáltatási időintervallum
ajánlati tartalom
pénzügyi összesítés
follow-up esetén utókövetési mezők

Kapcsolat a plannerrel

A quote PDF egyes mezőit a plannerből származó payload egészíti ki, de a quote továbbra is önálló domain marad.

21. Quote / CRM API referencia

POST /api/quotes/generate

ajánlat generálás

{
  "payload": {
    "coupleName": "Kovács Anna és Szabó Péter",
    "eventDate": "2026-07-18",
    "venue": "Szeged - Kastélykert Birtok"
  },
  "quote": {
    "packageName": "Esküvő – Prémium",
    "basePrice": 280000,
    "discountAmount": 10000,
    "status": "draft"
  }
}

{
  "ok": true,
  "stamp": "kovacs_anna_es_szabo_peter_2026-07-18_aj-2026-0001",
  "record": { ... },
  "pdf": "/data/quotes/....pdf",
  "json": "/data/quotes/....json"
}

GET /api/quotes

quote lista

/api/quotes?q=kovacs&status=accepted

GET /api/quote/:stamp

quote rekord lekérése

DELETE /api/quote/:stamp

quote törlése

22. Accepted quote import a plannerbe

A planner és a quote rendszer között egy külön integrációs pont létezik: az accepted quote import. Ennek célja, hogy az elfogadott ajánlatokból a planner oldal előtölthesse a releváns adatokat.

Endpointok

GET /api/planner-accepted-quotes
GET /api/planner-accepted-quote/:stamp

Miért külön service?

Mert ez nem egyszerű quote olvasás, hanem egy speciális planner-előkészítő workflow, amely csak accepted státuszú rekordokat enged át.

23. Dashboard rendszer

A dashboard domain aggregált áttekintést ad a planner és quote állományokról. A summary service több külön vizsgálatot futtat le: közelgő események, hiányosságok, nyitott pénzügyek, quote állapotok és összesített számossági mutatók.

Planner summary elemek

összes esemény
szerződött események
mai események
következő 7 nap eseményei
nyitott pénzügyek
hiányos rekordok

Quote summary elemek

összes quote
aktív quote-ok
accepted quote-ok
lejárt quote-ok
legfrissebb quote-ok

{
  "ok": true,
  "summary": {
    "totalEvents": 12,
    "contractedEvents": 8,
    "todayCount": 1,
    "next7DaysCount": 3,
    "openFinanceCount": 4
  },
  "nextEvent": { ... },
  "todayItems": [ ... ],
  "next7Days": [ ... ],
  "alerts": {
    "missingDeposit": [ ... ],
    "missingInvoiceInfo": [ ... ]
  },
  "quotes": {
    "totalQuotes": 18,
    "activeQuotes": 4,
    "acceptedQuotes": 6,
    "expiredQuotes": 3
  }
}

24. Calendar rendszer

A calendar service havi grid-alapú naptárstruktúrát készít a planner indexből. A cél az, hogy a frontend egy már előaggregált, naptár-kompatibilis adatszerkezetet kapjon.

Működés

A service kiolvassa a kiválasztott hónapba eső eseményeket, napi csoportosítást végez, majd egy teljes naptárrácsot állít elő előző és következő hónapból átnyúló napokkal együtt.

{
  "ok": true,
  "month": "2026-07",
  "monthLabel": "2026. július",
  "prevMonth": "2026-06",
  "nextMonth": "2026-08",
  "days": [
    {
      "date": "2026-07-18",
      "day": 18,
      "inMonth": true,
      "isToday": false,
      "items": [ ... ]
    }
  ]
}

25. Auth rendszer

Az auth réteg két külön végpontot kezel: dashboard és price-view hitelesítést. Technikai szinten mindkettő ugyanazt a master password logikát használhatja, de üzletileg külön maradtak.

Dashboard auth

A dashboard admin felület védelme.

{
  "password": "ateszadmin"
}

{
  "ok": true,
  "authorized": true
}

Price-view auth

A DJ preview / price-view oldali hitelesítés.

{
  "password": "ateszadmin"
}

{
  "ok": true,
  "authorized": true
}

A két endpoint külön maradt, mert eltérő frontend nézeteket szolgálnak ki. Ez tudatos üzleti duplikáció.

26. Support endpointok

A support réteg olyan közös háttérfunkciókat szolgáltat, amelyek nem kizárólag planner vagy quote domainekhez tartoznak, de a rendszer működéséhez szükségesek.

GET/api/venues

venue lista

POST/api/venues

új venue mentése

POST/api/upload

képfeltöltés

GET/api/payment-transfer-config

payment transfer config

GET/api/stats

statisztikák

27. Statisztikai logika

A stats service a planner indexből és a planner rekordokból készít gyakorisági összesítéseket. Ezek a dashboard riportok és elemzések hátterét adják.

Gyűjtött mutatók

top genres
top do not play tokenek
dinner frequency
cake frequency
venue frequency

További bontások

status frequency
paid frequency
dj tech frequency
összes session darabszám

28. Storage fájlok és létrejövési mátrix

Route	Művelet	Létrejövő / módosuló fájlok
`POST /api/sessions`	create/update	`/data/<stamp>.json`, `.pdf`, `.ics`, `_index.json`
`DELETE /api/session/:stamp`	delete	`/data/<stamp>.json`, `.pdf`, `.ics`, `_index.json`
`POST /api/quotes/generate`	create/update	`/data/quotes/<stamp>.json`, `.pdf`, `_quotes_index.json`, `_counters.json`
`DELETE /api/quote/:stamp`	delete	`/data/quotes/<stamp>.json`, `.pdf`, `_quotes_index.json`
`POST /api/upload`	create	`/uploads/<generated_file>`

29. Hibakezelési stratégia

A V2 hibakezelése megtartja a V1 státuszkód és válaszlogikáját, de a felelősségeket jobban szétválasztja.

Tipikus státuszkódok

200 – sikeres válasz
400 – validációs vagy input hiba
403 – üzleti tiltás
404 – rekord nem található
500 – belső szerverhiba

Jellemző hibaforrások

hiányzó kötelező mező
PDF generálási probléma
sérült JSON fájl
fájlrendszer-jogosultsági hiba
nem accepted quote import kísérlet

30. Duplikációkezelési elv

A V2 refaktor egyik alapelve az volt, hogy nem minden duplikációt kell megszüntetni. A rendszerben különbséget kell tenni a technikai és az üzleti duplikáció között.

Technikai duplikációk

Ezeket közös rétegbe lehetett emelni: JSON olvasás, atomic write, normalizálás, dátum- és pénzformázás.

Üzleti duplikációk

Ezek tudatosan megmaradtak külön: planner index és quote index, planner PDF és quote PDF, dashboard auth és price-view auth, planner mentés és quote mentés.

Azért maradtak meg külön ezek a logikák, mert nem minden hasonló endpoint vagy service csinál pontosan ugyanazt, és a túl korai közösítés regresszióhoz vezethetett volna.

31. Frontend és adat kompatibilitás

A V2 refaktor legfontosabb követelménye a teljes kompatibilitás volt a meglévő frontenddel és a korábban mentett adatokkal.

Frontend kompatibilitás

útvonalak változatlanok
request kulcsok változatlanok
response kulcsok változatlanok
státuszkódok változatlan logikával működnek

Adat kompatibilitás

planner JSON formátum nem változott
quote JSON formátum nem változott
index fájlok kompatibilisek maradtak
a korábbi exportok és mentések tovább használhatók

A refaktor után a backend a frontend oldaláról nézve ugyanúgy viselkedik, mint korábban. A változás a kódbázis belső szerkezetében történt.

32. További bővítési irányok

A V2 backend már alkalmas arra, hogy további fejlesztések biztonságosan ráépüljenek.

Schema alapú validáció A jelenlegi util-normalizálás később Zod vagy Joi alapú központi validációs réteggel bővíthető.

Erősebb auth A külön auth route-ok később tokenes vagy session alapú jogosultságkezelésre válthatók.

Tesztréteg A service-ek szétválasztása lehetővé teszi a célzott unit és integrációs tesztelést.

Storage bővítés A storage réteg miatt később akár részleges adatbázis vagy más persistence stratégia is bevezethető a route contract megtartása mellett.

A V2 legfontosabb eredménye, hogy a backend most már készen áll a következő fejlesztési szintre anélkül, hogy a jelenlegi működés vagy a frontend stabilitása sérülne.