2026.06.04 frontend építés közben

api_spec.md

@@ -0,0 +1,70 @@
+# API Specification: Hitelesítés és Felhasználói Profil
+
+Ez a dokumentum a felhasználó hitelesítéshez (login) és a felhasználói profil lekéréséhez tartozó backend szerződést (API specifikációt) írja le.
+
+## 1. Hitelesítési Mód
+A backend **JWT (JSON Web Token)** alapú hitelesítést használ.
+Az API végpontok (pl. profil lekérése) meghívásakor az access tokent a HTTP Header-ben kell átadni:
+`Authorization: Bearer <access_token>`
+
+Megjegyzés: A rendszer a `refresh_token`-t mind a JSON válaszban, mind egy HTTPOnly, Secure, SameSite=lax cookie-ban (`refresh_token` néven) visszaadja.
+
+## 2. Bejelentkezés (Login) API
+
+- **Végpont URL:** `POST /api/v1/auth/login`
+- **Content-Type:** `application/x-www-form-urlencoded`
+
+### Várt Request Body (Form Data)
+A végpont az OAuth2PasswordRequestForm szabványt követi.
+
+| Mező | Típus | Kötelező | Leírás |
+|---|---|---|---|
+| `username` | string | Igen | A felhasználó email címe. |
+| `password` | string | Igen | A felhasználó jelszava. |
+| `remember_me` | boolean | Nem | `true` esetén hosszabb lejárati idejű tokent ad (alapértelmezés: `false`). |
+| `grant_type` | string | Nem | Értéke általában `password` (OAuth2 specifikáció szerint). |
+
+### Visszaadott Response (JSON)
+Sikeres bejelentkezés esetén (HTTP 200 OK):
+
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1...",
+  "refresh_token": "eyJhbGciOiJIUzI1...",
+  "token_type": "bearer",
+  "is_active": true
+}
+```
+
+## 3. Felhasználói Profil Lekérése (Current User)
+
+- **Végpont URL:** `GET /api/v1/users/me` (Létezik egy alias is: `GET /api/v1/auth/me`)
+- **Hitelesítés:** Kötelező (Header: `Authorization: Bearer <access_token>`)
+
+### Visszaadott Response (JSON - `UserResponse` struktúra)
+A válasz tartalmazza a felhasználó alapadatait, valamint a jogosultsági és céges/privát kontextust meghatározó mezőket:
+
+```json
+{
+  "email": "user@example.com",
+  "first_name": "Gábor",
+  "last_name": "Kovács",
+  "is_active": true,
+  "region_code": "HU",
+  "id": 123,
+  "person_id": 456,
+  "role": "USER",
+  "subscription_plan": "FREE",
+  "scope_level": "individual",
+  "scope_id": "123",
+  "ui_mode": "personal",
+  "active_organization_id": null
+}
+```
+
+### Kiemelt mezők a jogosultsághoz és céges/privát kontextushoz:
+- **`role`**: A felhasználó rendszerszintű jogosultsági köre (pl. `USER`, `ADMIN`, `SUPERADMIN`).
+- **`scope_level`**: Meghatározza, hogy a felhasználó milyen szintű adatokhoz fér hozzá (pl. `individual`, `business`).
+- **`scope_id`**: A scope-hoz tartozó azonosító (pl. a saját user ID-ja vagy a szervezet ID-ja).
+- **`ui_mode`**: Meghatározza az aktuális felületi módot, ami lehet `personal` (privát) vagy `business` (céges nézet).
+- **`active_organization_id`**: Ha a felhasználó egy céges környezetbe van belépve, itt jelenik meg az aktív cég (szervezet) azonosítója (int/UUID). Ha privát módban van, az értéke `null`.