126 lines
4.9 KiB
Markdown
126 lines
4.9 KiB
Markdown
# 🏗️ 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]
|
|
```
|