service-finder/docs/V01_gemini/07_API_Guide.md

(API specifikáció.)

🔌 API GUIDE

Verziózás

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

Route Inventory (Kiemelt)

• POST /api/v2/auth/register (Regisztráció Person létrehozással)
• GET /api/v1/fleet/vehicles (Saját járművek listája)
• POST /api/v1/search/match (Szervizkereső algoritmus)
• POST /api/v1/evidence/upload (MinIO feltöltés)

Hiba Kezelés

• 401: Token lejárt -> Frontend dobjon Loginra.
• 403: Jogosultság hiba -> "Nincs jogod ehhez a funkcióhoz" (Tier limit).
• 404: Resource not found OR Soft Deleted.

🌐 8. 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.

8.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: hu.json, en.json, de.json.

8.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.

8.3. Nyelvválasztás logikája

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.

🛡️ 9. Unified Registration & Security Protocol

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

9.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 gombot/linket.
3. Step 2 (KYC): Sikeres verifikáció után a felhasználó megadja az okmányait (rugalmas választó: 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.

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

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

9.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 (pl. "Nem kaptam meg a kódot") 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.