service-finder/plans/logic_spec_unified_address_refactoring.md

🏗️ Logic Spec: Unified Address Refactoring

Dátum: 2026-07-01 Architect: Rendszer-Architect Cél: Az összes backend API végpont címkezelésének egységesítése az AddressIn/AddressOut P0 refactored sémára.

---

1. Jelenlegi Állapot

A rendszerben 3 féle cím séma és 2 teljesen eltérő címkezelési stratégia fut párhuzamosan.

1.1 Létező Cím Formátumok

#	Formátum	Fájl	Használja
1	AddressIn/AddressOut	schemas/address.py	organizations.py (✅ P0 refactored)
2	AddressResponse (address_* prefix)	schemas/user.py	users.py, admin_persons.py
3	Saját inline dict (postal_code, city, street)	admin.py	admin user list
4	Saját inline sémák (address, city, address_zip)	admin_providers.py	admin provider CRUD
5	Denormalizált address_* (3 féle)	admin_organizations.py	admin org CRUD
6	PersonAddressUpdate (address_* prefix)	admin_persons.py	admin person update
7	Saját sémák (address, address_zip)	schemas/provider.py	providers.py
8	Egyszerű string (city, address)	gamification.py	gamification

1.2 Kritikus Inkonzisztenciák

1. Mezőelnevezés: zip vs address_zip vs postal_code — 3 név, 1 adat
2. address_hrsz vs parcel_id — ugyanaz az adat, eltérő név
3. FK vs Denormalizált: system.addresses FK vs direkt mezők
4. Duplikált séma definíciók: admin_providers.py saját Pydantic osztályokkal

---

2. Cél Állapot

2.1 Target Schema: AddressIn / AddressOut

Bemenet (AddressIn): zip, city, street_name, street_type, house_number, stairwell, floor, door, parcel_id, full_address_text, latitude, longitude

Kimenet (AddressOut): id (UUID string), zip, city, street_name, street_type, house_number, stairwell, floor, door, parcel_id, full_address_text, latitude, longitude, created_at

2.2 Backend Modell: Address (system.addresses)

• FK postal_code_id → GeoPostalCode (zip/city resolution)
• Minden más mező direktben az Address táblában
• zip és city Python property-k

2.3 Elvek

1. Minden endpoint AddressIn-t vár bemenetként (nested object)
2. Minden endpoint AddressOut-ot ad vissza kimenetként (nested object)
3. AddressResponse eltávolítása, helyette AddressOut
4. PersonAddressUpdate eltávolítása, helyette AddressIn
5. Séma duplikációk megszüntetése

---

3. Implementációs Terv

🔴 P1 — Core Fixes (#386)

#	Fájl	Változtatás
1	admin.py	list_users: dict → AddressOut formátum
2	admin_persons.py	PersonAddressUpdate → AddressIn, AddressResponse → AddressOut

admin.py részletek:

• postal_code, city, street, house_number, address → address: Optional[AddressOut]
• AddressOut.model_validate(address) használata

admin_persons.py részletek:

• PersonAddressUpdate törlés → AddressIn import
• PersonUpdateRequest.address: Optional[PersonAddressUpdate] → Optional[AddressIn]
• PersonListItem.address: Optional[AddressResponse] → Optional[AddressOut]
• PersonDetailResponse.address: Optional[AddressResponse] → Optional[AddressOut]
• AddressResponse konstrukciók → AddressOut.model_validate(person.address)
• addr_data.address_zip → addr_data.zip, addr_data.address_hrsz → addr_data.parcel_id

🟡 P2 — Extended Unification

#	Issue	Fájl	Változtatás
3	#387	users.py	PersonUpdate denormalizált → AddressIn
4	#388	admin_providers.py	Inline sémák → AddressOut
5	#389	admin_organizations.py	3 féle denormalizált → AddressIn/AddressOut

🟢 P3 — Low Priority

#	Issue	Fájl	Változtatás
6	#390	schemas/provider.py + endpoint	ProviderSearchResult → AddressOut
7	#391	gamification.py	city/address → AddressIn

Phase 4: Cleanup

#	Fájl	Változtatás
8	schemas/user.py	AddressResponse eltávolítása
9	Import check	Minden AddressResponse → AddressOut

---

4. Adatbázis Érintettség

NINCS adatbázis séma változás! Csak Pydantic sémák és API réteg.

• Address modell (system.addresses) már létezik
• Denormalizált address_* mezők a szülő táblákban megmaradnak (későbbi cleanup)

---

5. Gitea Dependency Graph

graph TD
    A[#386 P1: admin.py + admin_persons.py] --> B[#387 P2: users.py]
    A --> C[#388 P2: admin_providers.py]
    A --> D[#389 P2: admin_organizations.py]
    B --> E[#390 P3: providers.py]
    C --> E
    D --> E
    E --> F[#391 P3: gamification.py]
    F --> G[Phase 4: Cleanup]