Wedding Planner / CRM - Backend fejlesztői dokumentáció

aktuális backend dokumentáció

Backend összkép

A backend Node.js + Express alapú. Az adatok továbbra is fájlalapon élnek, de a logika szolgáltatásokra bontva szerveződik. A legfontosabb cél a stabil napi működés, a gyors menthetőség és a könnyű restore maradt.

Node.js

Express

service réteg

signed cookie auth

JSON storage

PDF / ICS

backup / trash

1. Architektúra

A backend vékony route-okból és funkció szerint szétválasztott service-ekből áll. A route-ok fogadják a kérést, authot ellenőriznek és egységes JSON választ adnak vissza. Az üzleti logika a service rétegben marad.

Route réteg

A server/routes alatt él. Ide tartozik a planner, quotes, dashboard, calendar és support végpontok kezelése.

Service réteg

A server/services alatt külön mappákban van bontva: planner, quotes, dashboard, support, security, system, calendar, auth, pdf, stats.

Storage logika

A mentett állapot JSON és kapcsolódó fájlok formájában él. A rendszer indexfájlakat is fenntart a gyors listázáshoz.

2. Könyvtár- és storage modell

server/
├─ app.js
├─ middleware/
├─ routes/
├─ services/
└─ utils/

runtime/
├─ config/
├─ data/
│  ├─ _index.json
│  ├─ quotes/
│  │  ├─ _quotes_index.json
│  │  ├─ *.json
│  │  └─ *.pdf
│  ├─ trash/
│  └─ *.json / *.pdf / *.ics
├─ uploads/
└─ backups/

A planner rekordok a fő adatkönyvtárban, a quote rekordok a quotes alkönyvtárban élnek. A trash külön kezeli a törölt session, quote és egyéb visszaállítható elemeket.

A projekt továbbra sem adatbázist használ. A jelenlegi működés a fájlos modellre épül, ezért minden fejlesztésnél fontos a kompatibilitás a meglévő JSON szerkezettel.

3. Auth és admin feloldás

A rendszer admin jelszót használ, és sikeres hitelesítés után signed auth cookie-t ad. Ez a megoldás azért fontos, mert szerverújraindítás után is stabilan megmarad a feloldott állapot, amíg a cookie érvényes.

Első setup A rendszer ellenőrzi, hogy van-e admin jelszó konfigurálva.

Belépés A frontend auth endpointot hív, a backend ellenőrzi a jelszót és aláírt cookie-t ad vissza.

Védett műveletek A route-ok a cookie alapján autholnak, egyes admin funkciók pedig külön admin-headeres ellenőrzést is kérnek.

Újraindítás után A signed cookie miatt nem kell minden alkalommal újra promptolni a felhasználót.

4. Planner mentési flow

A planner mentés központi service-eken megy keresztül. A mentés most már úgy van szervezve, hogy ne maradjon félkész állapot, ha dokumentumgenerálás közben hiba történik.

Lépés	Mi történik?
Payload ellenőrzés	A backend validálja a fő rekord mezőit és előkészíti a mentendő objektumot.
Dokumentumok előállítása	PDF, ICS és szükség esetén szerződéses fájlok előkészítése történik.
Biztonságos csere	A végleges JSON és kapcsolódó fájlok csak sikeres generálás után kerülnek a helyükre.
Index frissítés	A session index upsert jelleggel frissül, nem teljes rebuilddel.
History és meta	Az előzmények és státuszmezők a rekordhoz íródnak.

5. Quote / CRM flow

A CRM külön quote életciklust kezel. Egy quote JSON + PDF párként mentődik, és a follow-up, státuszfrissítés, email preview és törlés is erre épül.

Endpoint / funkció	Leírás
`POST /api/quotes/generate`	Új quote JSON és PDF generálása.
`PATCH /api/quote/:stamp`	Meglévő ajánlat JSON frissítése follow-up vagy státuszváltás esetén.
`/email-preview` és `/send-email`	Ajánlat email előnézet és kiküldés.
Planner import meta	Az accepted quote rekordok jelölhetők, hogy bekerültek-e már a Plannerbe.

6. Dashboard és health API-k

A dashboard már nem csak statisztikai oldal. A backend summary és health service-ek operatív adatokat is visszaadnak, például prioritásos figyelmeztetéseket, nyitott pénzügyeket, importálatlan accepted quote-okat és rendszerállapotot.

Summary

A dashboard összesítő API több blokkra bontva ad vissza adatot: finance, alerts, recent updates, import listák és operatív elemek.

Health

A rendszerállapot ellenőrzi a szükséges runtime mappákat, kulcsfontosságú fájlokat, email konfigurációt és SMTP kapcsolatot.

Cache

A nehezebb ellenőrzések cache-eltek, hogy a dashboard ne lassuljon érezhetően.

7. Maintenance, backup, trash

A support és settings végpontok adják a karbantartási eszközöket. Ezek célja nem az, hogy napi szerkesztést váltsanak ki, hanem hogy üzembiztonsági hátteret adjanak.

Funkció	Mit csinál?
Global settings	Szolgáltatói, banki, email és sablonbeállítások olvasása és mentése.
Backup	Mentés létrehozása, listázása, restore és törlés.
Maintenance report	Indexek, uploadok, tmp fájlok és egyéb karbantartási állapot felderítése.
Trash	Törölt elemek visszaállítása vagy végleges törlése.
Restart	PM2 újraindítás és visszaellenőrzés.

8. Fontos fejlesztési szabályok

Szabály	Miért fontos?
A meglévő JSON szerkezetet csak indokolt esetben módosítsd	A rendszer élő adatokkal működik, a kompatibilitás elsődleges.
Indexet ne rebuildelj feleslegesen	A gyors dashboard és keresés a naprakész indexre épül.
Az authot a meglévő signed cookie modellre építsd	Ez biztosítja a restartbarát működést.
Új admin funkció support/settings vonalon jelenjen meg	Így a dashboard operatív fókusza tiszta marad.
Frontenddel egyező, ékezetes magyar szövegeket használj	A felület és a dokumentáció egységessége miatt.