service-finder/docs/address_api_consistency_audit.md

🏗️ Cím API Végpontok Egységességi Auditja

Dátum: 2026-07-01
Auditor: Rendszer-Architect
Cél: Annak ellenőrzése, hogy a címet kezelő API végpontok be- és kimeneti formátuma egységes-e, és alkalmas-e egy központi címmodul (Address Module) kezelésére.

---

📊 Összefoglaló

Verdikt: 🔴 NEM EGYSÉGES — 3 párhuzamos címformátum létezik, súlyos inkonzisztenciákkal.

A rendszerben jelenleg 3 féle cím séma és 2 teljesen eltérő címkezelési stratégia fut párhuzamosan. Egy központi címmodul bevezetése sürgős refaktorálást igényel.

---

🔍 Feltárt címformátumok

1. AddressIn / AddressOut (Unified P0 Refactored)

Fájl: backend/app/schemas/address.py

Mező	Típus	Leírás
zip	Optional[str]	Irányítószám
city	Optional[str]	Város
street_name	Optional[str]	Utca neve
street_type	Optional[str]	Közterület jellege
house_number	Optional[str]	Házszám
stairwell	Optional[str]	Lépcsőház
floor	Optional[str]	Emelet
door	Optional[str]	Ajtó
parcel_id	Optional[str]	Helyrajzi szám
full_address_text	Optional[str]	Teljes cím szöveg
latitude	Optional[float]	GPS szélesség
longitude	Optional[float]	GPS hosszúság

Használja: organizations.py (P0 refactored — nested AddressIn bemenet, AddressOut kimenet)

2. AddressResponse (user.py séma)

Fájl: backend/app/schemas/user.py

Mező	Típus	Eltérés
address_zip	Optional[str]	🟡 address_ előtaggal
address_city	Optional[str]	🟡 address_ előtaggal
address_street_name	Optional[str]
address_street_type	Optional[str]
address_house_number	Optional[str]
address_stairwell	Optional[str]
address_floor	Optional[str]
address_door	Optional[str]
address_hrsz	Optional[str]	🟡 eltérő név: hrsz vs parcel_id
full_address_text	Optional[str]
latitude	Optional[float]
longitude	Optional[float]

Használja: users.py (response), admin_persons.py (response + input: PersonAddressUpdate)

3. Admin endpointok saját belső sémái

Fájl: backend/app/api/v1/endpoints/admin_providers.py

Mező	Típus	Megjegyzés
address	Optional[str]	🟡 Szabad szöveges cím (legacy)
city	Optional[str]	🟡 city (előtag nélkül)
address_zip	Optional[str]	🟡 address_ előtaggal
address_street_name	Optional[str]
address_street_type	Optional[str]
address_house_number	Optional[str]
plus_code	Optional[str]	🟢 Csak itt van
contact_phone	Optional[str]

Használja: admin_providers.py (ProviderListItem, ProviderDetail, AdminProviderUpdate), admin_organizations.py

4. Admin user list (admin.py)

Fájl: backend/app/api/v1/endpoints/admin.py

Mező	Típus	Megjegyzés
postal_code	Optional[str]	🔴 Teljesen eltérő név
city	Optional[str]	🟡 előtag nélkül
street	Optional[str]	🔴 street (nem street_name)
house_number	Optional[str]	🟢 Ok
address	Optional[str]	🟡 Összefűzött string

---

🗺️ Érintett API Végpontok és Formátumuk

#	Végpont fájl	Cím bemenet	Cím kimenet	Formátum azonosság
1	organizations.py	AddressIn (nested)	AddressOut (nested)	✅ Egységes (P0)
2	users.py	Denormalizált address_*	AddressResponse (address_*)	⚠️ Részben
3	admin.py	—	Saját dict: postal_code, city, street	🔴 Eltérő
4	admin_providers.py	Saját AdminProviderUpdate	Saját ProviderDetail	⚠️ Részben
5	admin_organizations.py	Denormalizált address_*	Denormalizált address_*	⚠️ Részben
6	admin_persons.py	PersonAddressUpdate (address_*)	AddressResponse (address_*)	⚠️ Részben
7	providers.py	ProviderQuickAddIn / ProviderUpdateIn	ProviderSearchResult	⚠️ Saját séma
8	gamification.py	city, address (string)	—	🔴 Eltérő

---

🚨 Kritikus Inkonzisztenciák

1. 🔴 Mezőelnevezési konfliktus: zip vs address_zip vs postal_code

A 3 különböző séma 3 különböző néven hivatkozik ugyanarra az adatra:

• zip (AddressIn/AddressOut — P0 refactored)
• address_zip (AddressResponse, PersonUpdate — user séma)
• postal_code (admin.py user list response)

Következmény: A frontend fejlesztőknek tudniuk kell, hogy melyik endpoint melyik mezőnevet várja/adja. Ez magas hibalehetőséget hordoz.

2. 🔴 address_hrsz vs parcel_id — névütközés

• AddressResponse / PersonAddressUpdate: address_hrsz
• AddressIn / AddressOut: parcel_id
• Modell (Address): parcel_id

Következmény: Ugyanaz az adat (helyrajzi szám) két különböző néven szerepel.

3. 🔴 Kétféle címkezelési stratégia (FK vs denormalizált)

Stratégia A — Unified (P0 Refactored):

• system.addresses tábla + address_id FK
• AddressIn / AddressOut séma
• Használja: organizations.py

Stratégia B — Denormalizált:

• Címmezők közvetlenül a szülő táblában (address_city, address_zip, stb.)
• Külön Address entitás nélkül
• Használja: admin_organizations.py, admin_providers.py, providers.py, users.py

4. 🟡 Duplikált séma definíciók

Az admin_providers.py fájlban a ProviderListItem, ProviderDetail, AdminProviderCreate és AdminProviderUpdate osztályok saját Pydantic sémákként vannak definiálva a fájlon belül. Ezek mezői részben átfednek az AddressIn/AddressOut sémákkal, de nem azokat használják.

5. 🟡 ProviderSearchResult duplikált címmezőkkel

A ProviderSearchResult (backend/app/schemas/provider.py) tartalmaz egy address (string) mezőt és atomizált mezőket is (address_zip, address_street_name, stb.). Ez redundáns.

---

📋 Javasolt Refaktor Terv

Fázis 1: Egységes címmodul megerősítése

Az AddressIn/AddressOut séma megtartása és kiterjesztése:

class AddressIn(BaseModel):
    """Unified address input schema."""
    zip: Optional[str] = None
    city: Optional[str] = None
    street_name: Optional[str] = None
    street_type: Optional[str] = None
    house_number: Optional[str] = None
    stairwell: Optional[str] = None
    floor: Optional[str] = None
    door: Optional[str] = None
    parcel_id: Optional[str] = None
    full_address_text: Optional[str] = None
    latitude: Optional[float] = None
    longitude: Optional[float] = None

Fázis 2: Érintett endpointok átállítása

Prioritás	Végpont	Jelenlegi	Átállás
🔴 P1	admin.py user list	postal_code/city/street dict	AddressOut-ra váltás
🔴 P1	admin_persons.py	PersonAddressUpdate	AddressIn használata
🟡 P2	users.py	Denormalizált address_*	AddressIn + FK
🟡 P2	admin_providers.py	Saját ProviderDetail etc.	AddressOut beágyazás
🟡 P2	admin_organizations.py	Denormalizált address_*	AddressIn/AddressOut
🟢 P3	providers.py	ProviderSearchResult	AddressOut beágyazás
🟢 P3	gamification.py	city/address string	AddressIn használata

Fázis 3: AddressResponse eltávolítása

• AddressResponse (backend/app/schemas/user.py) → eltávolítani
• Helyette AddressOut-t használni mindenhol
• Frontend kompatibilitás: mapping réteg a frontenden, ha az address_* előtagot várja

---

⚙️ Technikai Megvalósítási Javaslat

Backend oldalon:

1. AddressIn bővítése country mezővel
2. Az összes admin endpoint átállítása AddressIn/AddressOut használatára
3. Organization modell denormalizált address_* mezőinek deprecated flaggelése
4. create_or_update_address service kiterjesztése az összes használati esetre

Frontend oldalon:

1. Egységes address komponens bevezetése, ami AddressOut formátumot vár
2. Mapping réteg a régi address_* formátumról az új AddressOut formátumra

---

📈 Következtetés

A rendszer JELENLEG NEM alkalmas egy központi címmodul kezelésére.

A P0 refactored AddressIn/AddressOut séma irányába történő elmozdulás elkezdődött (organizations.py), de a többi endpoint és séma még a régi, denormalizált megközelítést használja. A kettősség komoly karbantartási terhet és hibalehetőséget jelent.

Javasolt lépések:

1. 🔴 Azonnal: admin.py user list válasz átállítása AddressOut formátumra
2. 🔴 Rövidtávon: AddressResponse (user.py) és PersonAddressUpdate (admin_persons.py) lecserélése AddressOut/AddressIn-re
3. 🟡 Középtávon: Az összes admin provider/organization endpoint átállítása
4. 🟢 Hosszútávon: Provider sémák (ProviderSearchResult, ProviderQuickAddIn) átállítása