# 🏗️ 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

```mermaid
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]
```