kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity

FEAT: Integrated Document Engine with WebP optimization, Thumbnail generation and Hybrid (NAS/SSD) storage logic

Browse Source
This commit is contained in:
Kincses
2026-02-07 22:16:03 +00:00
parent e370ca3021
commit 4e14d57bf6
20 changed files with 657 additions and 607 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/V01_gemini/07_API_Guide.md
View File

@@ -1,56 +1,67 @@
(API specifikáció.)
# 🔌 API GUIDE
# 🔌 07_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`).
## 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`).
## 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.
## 2. Route Inventory (Kiemelt Végpontok)
Az alábbi táblázat tartalmazza a legfontosabb útvonalakat:
## 🌐 8. Nemzetköziesítés (i18n) és Lokalizáció
| 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) |
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
## 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: `hu.json`, `en.json`, `de.json`.
- **Példa fájlok:** `hu.json`, `en.json`, `de.json`.
### 8.2. Kezelési szabályok
### 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.
### 8.3. Nyelvválasztás logikája
### 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`.
# 🛡️ 9. Unified Registration & Security Protocol
---
A rendszer a "Minimal Friction, Maximum Security" elvét követi.
## 5. 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`.
### 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`.
### 9.2. Token Biztonsági Előírások
### 5.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)
### 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 (pl. "Nem kaptam meg a kódot") legkorábban 60 másodperc után lehetséges.
- **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.