Refactor: Auth & Identity System v1.4
- Fix: Resolved SQLAlchemy Mapper error for 'UserVehicle' using string-based relationships. - Fix: Fixed Postgres Enum case sensitivity issue for 'userrole' (forcing lowercase 'user'). - Fix: Resolved ImportError for 'create_access_token' in security module. - Feature: Implemented 2-step registration protocol (Lite Register -> KYC Step). - Data: Added bank-level KYC fields (mother's name, ID/Driver/Boat/Pilot license expiry and categories). - Business: Applied private fleet isolation (is_transferable=False for individual orgs). - Docs: Updated Grand Master Book to v1.4 and added Developer Pitfalls guide.
This commit is contained in:
@@ -1,5 +1,35 @@
|
||||
(Az Adatbázis Bibliája.)
|
||||
# 🗄️ DATABASE GUIDE
|
||||
# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.4)
|
||||
|
||||
## 1. Soft Delete & Újraregisztráció Logika
|
||||
A rendszerben nincs fizikai törlés. A `data.users` tábla az alábbi módon kezeli a visszatérő felhasználókat:
|
||||
- **Indexelés:** Az `email` mezőn egy *Partial Unique Index* (`idx_user_email_active_only`) található.
|
||||
- **Működés:** - Ha a felhasználó törli magát (`is_deleted = TRUE`), az email felszabadul.
|
||||
- Új regisztrációkor, ha a KYC adatok egyeznek, az új technikai User a régi `person_id`-hoz kapcsolódik.
|
||||
|
||||
## 2. Person (Identitás) - Banki KYC & Safety
|
||||
A `data.persons` tábla a valós identitást tárolja. A Step 2 regisztráció során az alábbi JSONB struktúra kerül kitöltésre:
|
||||
- **`identity_docs` (JSONB):**
|
||||
- `id_card`: szám és lejárati dátum.
|
||||
- `driver_license`: szám, lejárat és kategóriák (pl. ["A", "B", "C"]).
|
||||
- `special_permits`: hajóvezetői és repülőgép-vezetői engedélyek.
|
||||
- **`medical_emergency` (JSONB):** Vércsoport, allergiák, krónikus betegségek.
|
||||
- **Jutalom Trigger:** A profil 100%-os kitöltése után aktiválódik a `system_settings`-ben megadott PRÉMIUM időszak.
|
||||
|
||||
## 3. Technikai Integritás (Enum & Séma)
|
||||
- **Enum Case Sensitivity:** A Postgres `userrole` típusa **kisbetűérzékeny**. A Python kódból érkező értékeket (pl. `user`, `admin`) kényszerítve kisbetűvel kell rögzíteni.
|
||||
- **Séma Frissítés:** Mivel a `metadata.create_all` nem frissíti a meglévő táblákat, új oszlopok esetén (pl. `social_provider`, `mothers_name`) manuális `ALTER TABLE` vagy Alembic migráció szükséges.
|
||||
|
||||
## 4. Dinamikus Paraméterezés (`data.system_settings`)
|
||||
Minden üzleti változó Admin UI-ról állítható:
|
||||
- `auth.reward_days`: Regisztrációs prémium hossza (alapértelmezett: 14).
|
||||
- `referral.l1`: Első szintű jutalék % (alapértelmezett: 10).
|
||||
|
||||
## 5. Flotta Tulajdonjog Szabályok (v1.1)
|
||||
- **`INDIVIDUAL` flotta:** Nem átruházható (`is_transferable = False`), a felhasználóhoz kötött.
|
||||
- **`FLEET_OWNER / SERVICE` flotta:** Átruházható, új tulajdonoshoz rendelhető.
|
||||
|
||||
|
||||
# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.0)
|
||||
|
||||
|
||||
@@ -1,3 +1,88 @@
|
||||
# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4)
|
||||
|
||||
## I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT
|
||||
Az UX optimalizálása és a banki szintű biztonság érdekében a folyamat két külön fázisra oszlik.
|
||||
|
||||
### 1. Fázis: "Lite" Regisztráció (Step 1)
|
||||
* **Végpont:** `POST /api/v1/auth/register`
|
||||
* **Adatok:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
|
||||
* **Rendszeresemény:**
|
||||
* Létrejön a technikai `User` rekord.
|
||||
* **Állapot:** `is_active = False`.
|
||||
* **Szerepkör:** Kényszerített kisbetűs `user` (Postgres Enum fix).
|
||||
* **Megerősítés:** A rendszer kiküld egy aktiváló emailt egy hash kóddal.
|
||||
* **Válasz:** JWT token `status: pending_kyc` flaggel.
|
||||
|
||||
### 2. Fázis: Banki KYC & Aktiválás (Step 2)
|
||||
* **Végpont:** `POST /api/v1/auth/complete-kyc` (Fejlesztés alatt)
|
||||
* **Kötelező KYC adatok:**
|
||||
* Anyja születési neve, születési hely/idő.
|
||||
* Okmányadatok: Személyi igazolvány és Jogosítvány száma + lejárati idők.
|
||||
* Járműkategóriák (pl. A, B, C) és speciális engedélyek (hajó, repülő).
|
||||
* **Finalizálás (Atomi tranzakció):**
|
||||
1. **Person:** Identitás rögzítése a JSONB dokumentumtárral.
|
||||
2. **Wallet:** Pénztárca nyitása 0 egyenleggel.
|
||||
3. **Privát Flotta:** Automatikus szervezet létrehozása (`is_transferable = False`).
|
||||
4. **Tagság:** Felhasználó rögzítése a flotta tulajdonosaként.
|
||||
5. **Aktiválás:** `is_active = True` és hozzáférés a rendszerhez.
|
||||
|
||||
## II. TECHNIKAI SZABÁLYOK ÉS FIXEK
|
||||
* **Postgres Enum:** Minden szerepkört (role) kisbetűvel kell küldeni az adatbázis felé (`user`, nem `USER`).
|
||||
* **Dinamikus Paraméterek:** Az `auth.reward_days` (jutalom napok) és jutalék százalékok a `data.system_settings` táblából jönnek.
|
||||
* **Audit Trail:** Minden regisztrációs fázisról Audit Log készül.
|
||||
|
||||
# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4)
|
||||
|
||||
## I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT
|
||||
A rendszer a felhasználói élmény optimalizálása (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt.
|
||||
|
||||
### 1. Fázis: "Lite" Regisztráció (Step 1)
|
||||
* **Cél:** Gyors belépés és a technikai User fiók létrehozása.
|
||||
* **Kötelező mezők:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
|
||||
* **Rendszeresemény:**
|
||||
* Létrejön a `data.users` rekord.
|
||||
* **Állapot:** `is_active = False`.
|
||||
* **Szerepkör:** Kötelezően kisbetűs `user` (Postgres Enum kényszerítés miatt).
|
||||
* **Email:** A rendszer azonnal kiküld egy ellenőrző emailt egy egyedi hash kóddal/linkkel.
|
||||
* **Token:** Az API egy korlátozott JWT tokent ad vissza, amely csak a Step 2 végpont elérésére jogosít (`status: pending_kyc`).
|
||||
|
||||
### 2. Fázis: KYC & Aktiválás (Step 2)
|
||||
* **Cél:** A valós identitás (Person) rögzítése és a gazdasági egységek inicializálása.
|
||||
* **Kötelező adatok (Identity Verification):**
|
||||
* **Személyes:** Anyja születési neve, születési hely, születési idő.
|
||||
* **Okmányok:** Személyi igazolvány száma és lejárati ideje.
|
||||
* **Jogosítvány:** Vezetői engedély száma, lejárata és kategóriák (pl. AM, A, B, C, CE).
|
||||
* **Speciális:** Hajóvezetői és repülőgép-vezetői engedély adatai (ha releváns).
|
||||
* **Működés:** A felhasználó csak ezen adatok kitöltése és sikeres ellenőrzése után válik teljes jogú taggá.
|
||||
|
||||
### 3. Fázis: Atomi Tranzakció (Finalization)
|
||||
A KYC adatok beküldésekor a rendszer egyetlen adatbázis-tranzakcióban (`Atomic`) hajtja végre az alábbiakat:
|
||||
1. **Person létrehozása:** A KYC adatok és okmánymásolatok (JSONB) rögzítése.
|
||||
2. **Wallet inicializálás:** 0 Coin és 0 XP egyenleggel.
|
||||
3. **Privát Flotta (Private Org):** Létrejön a felhasználó saját cége (`OrgType.INDIVIDUAL`), amely **nem átruházható** (`is_transferable = False`).
|
||||
4. **Aktiválás:** A User fiók `is_active = True` állapotba kerül.
|
||||
5. **Audit:** Bejegyzés az `audit_logs` táblába a teljes körű regisztrációról.
|
||||
|
||||
## II. MEGHÍVÓ ÉS JUTALÉK LOGIKA
|
||||
* **Invite Tokenek:**
|
||||
* `REG_ONLY`: Általános meghívó, beköti a felhasználót a 10-5-2% jutalék láncba.
|
||||
* `COMPANY_JOIN`: Meghatározott szervezetbe hív (CEO, Flotta Manager vagy Sofőr szerepkörbe).
|
||||
* **Kredit Jóváírás:**
|
||||
* Csak az **első** Prémium csomag befizetésekor történik jutalékfizetés a meghívási láncban.
|
||||
* A százalékos mérték (10%, 5% vagy 2%) a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot).
|
||||
|
||||
## III. TECHNIKAI ÉS BIZTONSÁGI SZABÁLYOK
|
||||
* **Enum Case Sensitivity:** A PostgreSQL `userrole` típusa miatt minden Enum értéket (user, admin, driver, service, fleet_manager) szigorúan **kisbetűvel** kell kezelni.
|
||||
* **Dinamikus Paraméterezés:** Tilos fix értékeket (hardcoded) használni. Az alábbiakat a `data.system_settings` táblából kell lekérni:
|
||||
* `auth.reward_days`: Regisztrációkor járó prémium napok (alapértelmezett: 14).
|
||||
* `referral.level1-3`: Jutalék szintek mértéke.
|
||||
* **Email Manager:** A `send_email` hívásakor tilos a `subject` paraméter átadása; a szerviz a `template_key` alapján automatikusan generálja azt.
|
||||
* **Szigorú Helyreállítás:** A banki szintű KYC után a jelszó-visszaállítás kérhető a Person adatok (Anyja neve, Okmány szám) megadásával is.
|
||||
|
||||
## IV. SOCIAL AUTH (GOOGLE / FACEBOOK)
|
||||
* Social Auth esetén a Step 1 lerövidül, de a **Step 2 (KYC) kötelező** marad az aktiváláshoz.
|
||||
* Amíg a KYC hiányzik, a felhasználó "GUEST" státuszban marad, és nem fér hozzá a flottakezeléshez.
|
||||
|
||||
# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.1)
|
||||
|
||||
## 1. Hibakezelési Jegyzet (TypeError fix)
|
||||
|
||||
@@ -1,6 +1,26 @@
|
||||
(Mit csinálunk most?)
|
||||
# 🗺️ ROADMAP & TECH DEBT
|
||||
|
||||
# 🗺️ ROADMAP & TECH DEBT (v1.4)
|
||||
|
||||
## 🚧 SPRINT 1 (Azonnali - Stabilitás)
|
||||
1. **Frontend Config:** Hardkódolt IP-k cseréje `.env` változókra.
|
||||
2. **Step 1 Regisztráció Fix:** A meglévő endpoint átalakítása "Lite" regisztrációra (csak User létrehozás, `is_active=False`).
|
||||
3. **Enum Case Sensitivity:** Minden DB query felülvizsgálata, hogy a `role` mező kényszerítve kisbetűs legyen.
|
||||
4. **Security Module:** `create_access_token` és `verify_password` funkciók véglegesítése a `core/security.py`-ban.
|
||||
|
||||
## 🚧 SPRINT 2 (KYC & Onboarding)
|
||||
1. **Step 2 KYC Endpoint:** `POST /api/v1/auth/complete-kyc` megvalósítása.
|
||||
2. **Atomi Tranzakció Logic:** A Person, Wallet és Private Org egyidejű létrehozása a KYC beküldésekor.
|
||||
3. **Verification Email:** Aktiváló link generálása és kiküldése hash kóddal.
|
||||
4. **Admin UI Settings:** Felület a `system_settings` tábla kezeléséhez.
|
||||
|
||||
## 📅 SPRINT 3 (Marketplace MVP)
|
||||
1. **OCR Pipeline:** Számla/Okmány fotó feltöltés MinIO-ba + AI validáció teszt.
|
||||
2. **Service Request:** Frontend űrlap ajánlatkéréshez.
|
||||
|
||||
|
||||
# ROADMAP & TECH DEBT (v1.0)
|
||||
## 🚧 SPRINT 1 (Azonnali)
|
||||
1. **Frontend Config:** Hardkódolt IP-k cseréje `.env` változókra.
|
||||
2. **Person Migráció:** DB szkript futtatása (User -> Person).
|
||||
|
||||
@@ -27,4 +27,52 @@
|
||||
- **Security:** "Kill-switch" anomália-figyelés és 2FA kényszerítés rögzítve.
|
||||
- **Economy:** 10-5-2% jutalékrendszer és Voucher/Coupon logika specifikálva.
|
||||
- **Synergy:** Céges VIP és privát flotta közötti kedvezmény-szinergia kidolgozva.
|
||||
- **Invitations:** Meghívó limitációs és anti-spam logika rögzítve.
|
||||
- **Invitations:** Meghívó limitációs és anti-spam logika rögzítve.
|
||||
|
||||
# 📓 CHANGELOG - SERVICE FINDER
|
||||
|
||||
## [1.2.1] - 2026-02-05
|
||||
### ✅ Hozzáadva (Added)
|
||||
- **Multi-step Social Auth:** `User` modell bővítve `social_provider` és `social_id` mezőkkel.
|
||||
- **Flotta Tulajdonjog:** `Organization` modellben `is_transferable` flag implementálva (Individual flotta zárolva).
|
||||
- **Referral Snapshot:** Előkészítve a 10-5-2%-os jutalékrendszer adatmodellje.
|
||||
|
||||
### 🛠️ Javítva (Fixed)
|
||||
- **SQLAlchemy Mapper:** Megszűnt a `UserVehicle` KeyError hiba a string-alapú hivatkozásokkal.
|
||||
- **Duplikáció:** `Vehicle` osztály duplikációja eltávolítva a `vehicle.py`-ból.
|
||||
- **Indentation Error:** `security.py` bcrypt indentációs hiba javítva.
|
||||
|
||||
### ⚠️ Megjegyzés
|
||||
- Alembic migráció szükséges az új `Organization` és `User` mezőkhöz.
|
||||
|
||||
📓 CHANGELOG (Rögzítendő változások)
|
||||
|
||||
Mivel kérted, itt van a változások listája, amit a teszt után beírhatunk:
|
||||
|
||||
Fixed: UserRole enum validációs hiba (Postgres userrole típus mostantól kisbetűs értéket kap).
|
||||
|
||||
Added: Teljes banki KYC integráció a regisztrációba (Személyi, Jogosítvány, Speciális engedélyek).
|
||||
|
||||
Added: Atomi tranzakció részeként automatikus OrganizationMember létrehozás a privát flottához.
|
||||
|
||||
Added: Audit log rögzítése minden sikeres regisztrációról.
|
||||
|
||||
Added: Dinamikus paraméterkezelés (system_settings) a 14 napos jutalomhoz.
|
||||
|
||||
Elvárt eredmény: A tranzakció végén létrejön a Person, a Wallet (0 Coin) és a Private Fleet (is_transferable=False). A User is_active értéke True lesz.
|
||||
|
||||
3. Debugging Checklist
|
||||
|
||||
500 Error? Ellenőrizd a docker logs -f service_finder_api kimenetét. Ha "UndefinedColumn", akkor hiányzik egy SQL mező. Ha "InvalidTextRepresentation", akkor Enum hiba (nagybetűs string).
|
||||
|
||||
Üres Swagger? Ellenőrizd az importokat a security.py-ban és a sémákat az endpoints/auth.py-ban.
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 💡 Javaslatom a dokumentáció kiegészítésére:
|
||||
A fejlesztések rendben tartásához javaslom a **`17_DEVELOPER_NOTES_AND_PITFALLS.md`** fájl aktív használatát is, amit az előző körben küldtem. Ez segít megelőzni, hogy a fejlesztőcsapat újra belefusson a Postgres Enum vagy a `Base.metadata.create_all` korlátaiba.
|
||||
|
||||
|
||||
|
||||
**Holnap reggel frissíted a GEM beállításokat is?** Ha igen, a következő lépésben elkészíthetem neked a Step 2 (KYC) végleges Pydantic sémáját és a `complete-kyc` végpont vázlatát!
|
||||
@@ -1,3 +1,27 @@
|
||||
# 🧪 TESZTELÉSI ÉS ÉLESÍTÉSI ÚTMUTATÓ (v1.4)
|
||||
|
||||
## 1. Előkészületek és Környezet
|
||||
1. **SQL Patch:** Meglévő adatbázis esetén futtasd a manuális frissítő SQL-t (mothers_name, social_provider, is_transferable oszlopok hozzáadása).
|
||||
2. **Enum Ellenőrzés:** Győződj meg róla, hogy a Postgres `userrole` típus tartalmazza a kisbetűs értékeket.
|
||||
3. **Docker Build:** `docker compose up -d --build` (Kényszeríti az új Python kód betöltését).
|
||||
|
||||
## 2. Regisztrációs Teszt Forgatókönyvek
|
||||
|
||||
### A) Step 1: Lite Regisztráció (Clean Test)
|
||||
- **Endpoint:** `POST /api/v1/auth/register`
|
||||
- **Elvárt eredmény:** 201 Created, `access_token` visszaadva, de a DB-ben a User `is_active = False` és nincs hozzá Person rekord.
|
||||
|
||||
### B) Step 2: KYC Kitöltés (Advanced Test)
|
||||
- **Endpoint:** `POST /api/v1/auth/complete-kyc`
|
||||
- **Adat (JSON):**
|
||||
```json
|
||||
{
|
||||
"mothers_name": "Minta Mária",
|
||||
"id_card_number": "AB123456",
|
||||
"driver_license_categories": ["A", "B"],
|
||||
"boat_license_number": "H-99999"
|
||||
}
|
||||
|
||||
# 🧪 TESZTELÉSI ÉS ÉLESÍTÉSI ÚTMUTATÓ (v1.0)
|
||||
|
||||
## 1. Előkészületek a távoli teszteléshez
|
||||
|
||||
19
docs/V01_gemini/17_DEVELOPER_NOTES_AND_PITFALLS.md
Normal file
19
docs/V01_gemini/17_DEVELOPER_NOTES_AND_PITFALLS.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# 🛠️ DEVELOPER NOTES & TROUBLESHOOTING
|
||||
|
||||
## 1. ADATBÁZIS ÉS SQL FIXEK
|
||||
### Postgres Enum Case Sensitivity
|
||||
* **Probléma:** Az SQLAlchemy Enum típusa és a Postgres Enum típusa ütközhet, ha a Python kódban nagybetűs stringet (`USER`) küldünk.
|
||||
* **Megoldás:** Mindig használd a `.value` property-t vagy kényszerítsd a kisbetűs stringet: `role="user"`.
|
||||
|
||||
### Tábla oszlopok frissítése
|
||||
* **Probléma:** A `Base.metadata.create_all` nem adja hozzá az új oszlopokat a már meglévő táblákhoz.
|
||||
* **Megoldás:** Új mező esetén (pl. `social_provider`, `mothers_name`) manuális `ALTER TABLE` parancsot kell futtatni vagy Alembic migrációt generálni.
|
||||
|
||||
## 2. BACKEND API HIBÁK
|
||||
### ImportError: create_access_token
|
||||
* **Ok:** A `app.core.security` modulban hiányzott a funkció, vagy elavult volt az import az `endpoints/auth.py`-ban.
|
||||
* **Javítás:** A `security.py`-nak tartalmaznia kell a `jose` könyvtárat használó tokengenerálást.
|
||||
|
||||
### Üres Swagger (OpenAPI) felület
|
||||
* **Ok:** Ha az SQLAlchemy Mapper vagy egy Pydantic séma importja hibás, a FastAPI nem tudja legenerálni a dokumentációt.
|
||||
* **Javítás:** Ellenőrizd a `docker logs` kimenetét indításkor, keresd a `MapperConfigurationError` vagy `ImportError` sorokat.
|
||||
Reference in New Issue
Block a user