service-finder/archive/2026.02.18 Archive_old_mapps/V01_gemini/07_API_Guide.md

🔌 07_API_GUIDE

1. Verziózás (Versioning)

A rendszer támogatja a többszintű verziókezelést a stabilitás és a visszafelé való kompatibilitás érdekében.

• v1: Core Fleet funkciók (pl. /api/v1/vehicles, /api/v1/expenses).
• v2: Auth és új generációs modulok (pl. /api/v2/auth/login).

---

2. Route Inventory (Kiemelt Végpontok)

Az alábbi táblázat tartalmazza a legfontosabb útvonalakat:

Metódus	Végpont	Leírás
POST	/api/v2/auth/register	Regisztráció Person rekord létrehozásával
GET	/api/v1/fleet/vehicles	Felhasználó saját járműveinek listázása
POST	/api/v1/search/match	Szervizkereső algoritmus indítása
POST	/api/v1/evidence/upload	Dokumentum feltöltés (MinIO)

---

3. Hiba Kezelés (Error Handling)

A frontendnek az alábbi HTTP státuszkódok alapján kell lekezelnie a kivételeket:

• 401: Token lejárt -> Frontendnek automatikusan a Login oldalra kell dobnia a felhasználót.
• 403: Jogosultság hiba -> "Nincs jogod ehhez a funkcióhoz" üzenet megjelenítése (Tier limit/Role hiba).
• 404: Resource not found -> Az erőforrás nem található vagy Soft Deleted állapotban van.

---

4. Nemzetköziesítés (i18n) és Lokalizáció

A rendszer a "Global-Local" elv alapján működik. Tilos a programkódban (hard-coded) szöveges üzeneteket elhelyezni.

4.1. Nyelvi fájlok struktúrája

Minden nyelvi fájl a backend/app/locales/ mappában található, szabványos JSON formátumban.

• Példa fájlok: hu.json, en.json, de.json.

4.2. Kezelési szabályok

• Backend: A rendszerüzeneteket, hibaüzeneteket és az e-mail sablonok tartalmát a LocaleManager szolgáltatáson keresztül kéri le.
• Paraméterezés: A szövegekben használható változók formátuma: {variable_name}.
• Sablonkezelés: Az e-mailek HTML vázát és a JSON-ban tárolt szöveges blokkokat a rendszer a küldés előtt fűzi össze.

4.3. Nyelvválasztás logikája (Prioritás)

1. A kérés fejlécében érkező Accept-Language alapján.
2. Bejelentkezett felhasználó esetén a User.region_code alapján.
3. Alapértelmezett: hu.

---

5. Unified Registration & Security Protocol

A rendszer a "Minimal Friction, Maximum Security" elvét követi.

5.1. Regisztrációs Életciklus

1. Step 1 (Lite): Email, Jelszó, Név megadása. Létrejön a User és Person rekord. Állapot: is_active: false.
2. Verifikáció: A rendszer UUID alapú tokent generál (48 órás élettartam). A felhasználó e-mailben kap egy aktiváló linket.
3. Step 2 (KYC): Sikeres verifikáció után a felhasználó megadja az okmányait (Személyi/Jogsi/Hajó).
4. Aktiválás: Létrejön a Privát Flotta (Privát Széf) és a hozzá tartozó Wallet. Állapot: is_active: true.

5.2. Token Biztonsági Előírások

• Regisztrációs Token: 48 óra élettartam.
• Jelszó-visszaállítási Token: 1 óra élettartam.

5.3. Rate Limiting (Robotvédelem és Költségkontroll)

Az e-mail küldési folyamatokra az alábbi korlátok vonatkoznak:

• Retry Cooldown: Újraigénylés legkorábban 60 másodperc után lehetséges.
• Óránkénti Limit: Maximum 3 kérelem / e-mail cím.
• Napi Limit: Maximum 10 kérelem / e-mail cím.
• Zárolás: A napi limit túllépése esetén a fiók biztonsági okokból 24 órára zárolja a küldési funkciót az adott címre.

4. Geo és Kereső Végpontok

GET /api/v1/services/suggest-street

• Cél: Autocomplete támogatás a frontendnek.
• Paraméterek: zip_code (string), q (részleges utcanév).

GET /api/v1/services/search

• Cél: Kétlépcsős szervizkereső.
• Free mód: Légvonalbeli távolságmérés (Radius).
• Premium mód: Útvonal-idő alapú kalkuláció és forgalmi becslés.