# 🏗️ P0 Architect Report: Backend API & Validation Audit — Vehicle Management & Finance

**Dátum:** 2026-06-21  
**Auditor:** Rendszer-Architect  
**Státusz:** Read-Only Audit (Kódmódosítás nélkül)  
**Scope:** Vehicle CRUD, Pydantic Schemas, Fleet Finance Endpoints

---

## Executive Summary

Két kritikus gapet azonosítottam a Backend API és a Database Modellek között:

### 🔴 Critical Gap #1 — 6 Hiányzó Internationalizációs Mező a Schemákból és Service Logikából
Az `Asset` modell (backend/app/models/vehicle/asset.py:147) tartalmaz 6 új mezőt (`registration_country`, `first_domestic_registration_date`, `import_country`, `title_document_number`, `engine_number`, `number_of_previous_owners`), amelyek:
- **Hiányoznak** az `AssetCreate` (backend/app/schemas/asset.py:122) és `AssetUpdate` (backend/app/schemas/asset.py:269) Pydantic sémákból
- **Hiányoznak** a `create_or_claim_vehicle()` service metódus `asset_fields` dict-jéből (backend/app/services/asset_service.py:172-224)
- **Hiányoznak** az update logikából (backend/app/services/asset_service.py)

### 🔴 Critical Gap #2 — ZERO API Endpoint a Fleet Finance Modellekhez
A `fleet_finance` séma 4 modellje (`AssetFinancials`, `VehicleInsurancePolicy`, `VehicleTaxObligation`, `InsuranceProvider`) rendelkezik adatbázis táblákkal, de:
- **0 Pydantic schema** létezik hozzájuk (a schemas/finance.py csak `Issuer` sémákat tartalmaz)
- **0 API endpoint** létezik hozzájuk (az endpoints/finance_admin.py csak Issuer managementet tartalmaz)
- `AssetFinancials` csak a `create_or_claim_vehicle()` által kerül inicializálásra (nullákkal és `financing_type="unknown"`), de SOHA nem frissíthető az API-n keresztül

---

## 1. Section: Vehicle Schemas and Endpoints Status

### 1.1 Valódi Végpont Lokáció
⚠️ **Critical finding:** A `endpoints/vehicles.py` fájl NEM a jármű CRUD-ot tartalmazza, hanem kizárólag szociális értékeléseket (`VehicleUserRating`).  
A tényleges jármű CRUD a `endpoints/assets.py` fájlban található:
- `POST /api/v1/assets/vehicles` → `create_or_claim_vehicle()` (backend/app/api/v1/endpoints/assets.py:502)
- `PUT /api/v1/assets/vehicles/{asset_id}` → `update_vehicle()` (backend/app/api/v1/endpoints/assets.py:606)
- `GET /api/v1/assets/vehicles` → `get_user_vehicles()` (backend/app/api/v1/endpoints/assets.py:223)
- `GET /api/v1/assets/vehicles/{vehicle_id}` → `get_vehicle()` (backend/app/api/v1/endpoints/assets.py:439)

### 1.2 Hiányzó Mezők Mátrixa

| Mező | Asset Modell | AssetCreate Schema | AssetUpdate Schema | Service Logika |
|------|-------------|-------------------|-------------------|---------------|
| `registration_country` (ISO 3166-1 alpha-2) | ✅ (line 147) | ❌ | ❌ | ❌ |
| `first_domestic_registration_date` | ✅ (line 151) | ❌ | ❌ | ❌ |
| `import_country` (ISO 3166-1 alpha-2) | ✅ (line 155) | ❌ | ❌ | ❌ |
| `title_document_number` | ✅ (line 159) | ❌ | ❌ | ❌ |
| `engine_number` | ✅ (line 163) | ❌ | ❌ | ❌ |
| `number_of_previous_owners` | ✅ (line 167) | ❌ | ❌ | ❌ |

### 1.3 Meglévő Validátorok Állapota
Az `AssetCreate` séma jelenleg az alábbi validátorokat tartalmazza:
- `empty_str_to_none` — minden string mezőre (backend/app/schemas/asset.py:134)
- `normalize_brand` / `normalize_model` — brand/model normalizálás (backend/app/schemas/asset.py:143)
- `normalize_individual_equipment` — equipment lista normalizálás (backend/app/schemas/asset.py:159)
- `validate_vin_or_plate` — VIN vagy rendszám kötelezőség (backend/app/schemas/asset.py:183)
- `determine_status` — alapértelmezett DRAFT státusz (backend/app/schemas/asset.py:249)

**Hiányzó validátorok az új mezőkhöz:**
- `registration_country`: ISO 3166-1 alpha-2 formátum validátor (2 karakter, nagybetű)
- `import_country`: ISO 3166-1 alpha-2 formátum validátor
- `first_domestic_registration_date`: nem lehet jövőbeli dátum
- `number_of_previous_owners`: >= 0 integer validáció

---

## 2. Section: Financial Endpoints Status

### 2.1 Fleet Finance Modellek — Orphan Analysis

| Modell | DB Tábla Létezik? | Pydantic Schema? | API Endpoint? | API-n elérhető? |
|--------|------------------|-----------------|---------------|-----------------|
| `AssetFinancials` (backend/app/models/fleet_finance/models.py:141) | ✅ | ❌ | ❌ | ❌ (csak create-nél inicializálva) |
| `InsuranceProvider` (backend/app/models/fleet_finance/models.py:180) | ✅ | ❌ | ❌ | ❌ |
| `VehicleInsurancePolicy` (backend/app/models/fleet_finance/models.py:208) | ✅ | ❌ | ❌ | ❌ |
| `VehicleTaxObligation` (backend/app/models/fleet_finance/models.py:252) | ✅ | ❌ | ❌ | ❌ |

### 2.2 AssetFinancials Inicializálás
A `create_or_claim_vehicle()` (backend/app/services/asset_service.py:273) az alábbi módon hozza létre az `AssetFinancials` rekordot:
```
financials = AssetFinancials(
    asset_id=asset.id,
    purchase_price_net=Decimal("0"),
    purchase_price_gross=Decimal("0"),
    down_payment=Decimal("0"),
    monthly_installment=Decimal("0"),
    residual_value=Decimal("0"),
    financing_type="unknown"
)
```

Ez a rekord SOHA nem frissíthető az API-n keresztül, mert:
- Nincs `PATCH /assets/{asset_id}/financials` végpont
- Nincs `PUT /assets/{asset_id}/financials` végpont

### 2.3 Meglévő Finance Végpontok
A `endpoints/expenses.py` tartalmazza az `AssetCost` CRUD-ot (költség típusú adatok), de a pénzügyi/finanszírozási adatok teljesen hiányoznak.

A `endpoints/finance_admin.py` csak `Issuer` menedzsmentet tartalmaz (kibocsátók kezelése), semmi köze a fleet finance modelljeihez.

### 2.4 Meglévő Pydantic Schémák a Finance Domainben
- `schemas/finance.py` — csak `IssuerResponse` és `IssuerUpdate`
- `schemas/fleet.py` — csak `EventCreate` és `TCOStats` (minimális)

---

## 3. Section: Frontend Form Data Structure Recommendations

A jelenlegi frontend `VehicleFormModal.vue` formája nem tartalmazza a 6 hiányzó internationalizációs mezőt, és nem kommunikál a fleet finance modellekkel.

### Ajánlott Payload Csoportosítás

Az új frontend form structure az alábbi logikai csoportokra bontható:

**A csoport — Alapadatok (Basic Info)**
- `brand`, `model`, `generation_name`, `trim_level`, `year`
- `license_plate`, `vin`
- `vehicle_class`, `body_type`

**B csoport — Regisztrációs adatok (Registration)**
- `registration_country` (ISO 3166-1 alpha-2 dropdown)
- `first_domestic_registration_date` (datepicker)
- `registration_certificate_number`
- `registration_certificate_validity`
- `vehicle_registration_document_number`
- `title_document_number`

**C csoport — Import adatok (Import)**
- `import_country` (ISO 3166-1 alpha-2 dropdown)
- `engine_number`

**D csoport — Tulajdonlás (Ownership)**
- `number_of_previous_owners`
- `color`, `mileage`, `fuel_type`, `transmission_type`
- `individual_equipment`

**E csoport — Pénzügyi adatok (Financials) — ÚJ endpoint**
- `purchase_price_net` / `purchase_price_gross`
- `down_payment`, `monthly_installment`, `residual_value`
- `financing_type`, `financing_provider`, `contract_number`
- `interest_rate`, `lease_start_date`, `lease_end_date`

**F csoport — Biztosítás és Adó (Insurance & Tax) — ÚJ endpoint**
- `insurance_type`, `policy_number`, `start_date`, `expiry_date`, `premium_amount`, `provider_id`
- `tax_type`, `tax_year`, `amount`, `due_date`, `payment_status`

### API Végpont Javaslatok

A frontend számára az alábbi új REST végpontokra lenne szükség:

1. `PATCH /api/v1/assets/vehicles/{asset_id}/financials` — AssetFinancials frissítése
2. `GET /api/v1/assets/vehicles/{asset_id}/financials` — AssetFinancials lekérése
3. `POST /api/v1/assets/vehicles/{asset_id}/insurance` — Biztosítási kötvény hozzáadása
4. `GET /api/v1/assets/vehicles/{asset_id}/insurance` — Biztosítási kötvények listázása
5. `POST /api/v1/assets/vehicles/{asset_id}/tax` — Adókötelezettség hozzáadása
6. `GET /api/v1/assets/vehicles/{asset_id}/tax` — Adókötelezettségek listázása

---

## 4. Section: Recommended Action Plan

### Phase 1 — Backend (Backend API javítások)

| # | Feladat | Érintett fájl(ok) | Priority |
|---|---------|-------------------|----------|
| 1 | Add 6 hiányzó mezőt az `AssetCreate` és `AssetUpdate` sémákhoz | schemas/asset.py | P0 |
| 2 | Add ISO 3166-1 alpha-2 validátor a `registration_country` és `import_country` mezőkhöz | schemas/asset.py | P0 |
| 3 | Add `first_domestic_registration_date` jövőbeli dátum tiltás | schemas/asset.py | P0 |
| 4 | Egészítsd ki a `create_or_claim_vehicle()` logikát a 6 új mezővel | services/asset_service.py | P0 |
| 5 | Hozd létre az `AssetFinancialsUpdate` Pydantic sémát | schemas/finance.py (új) | P1 |
| 6 | Hozd létre a `VehicleInsurancePolicyCreate/Response` sémákat | schemas/finance.py (új) | P1 |
| 7 | Hozd létre a `VehicleTaxObligationCreate/Response` sémákat | schemas/finance.py (új) | P1 |
| 8 | Implementáld a `PATCH /assets/{asset_id}/financials` végpontot | endpoints/assets.py (új) | P1 |
| 9 | Implementáld a `POST/GET /assets/{asset_id}/insurance` végpontokat | endpoints/assets.py (új) | P1 |
| 10 | Implementáld a `POST/GET /assets/{asset_id}/tax` végpontokat | endpoints/assets.py (új) | P1 |

### Phase 2 — Frontend (UI komponensek bővítése)

| # | Feladat | Érintett komponens | Priority |
|---|---------|-------------------|----------|
| 1 | Bővítsd a `VehicleFormModal.vue` űrlapot a B, C, D csoport mezőivel | VehicleFormModal.vue | P1 |
| 2 | Hozz létre egy új `FinancialsTab.vue` komponenst (E csoport) | (új fájl) | P1 |
| 3 | Hozz létre egy új `InsuranceTaxTab.vue` komponenst (F csoport) | (új fájl) | P1 |
| 4 | Integráld az új tabeket a `VehicleDetailModal.vue` komponensbe | VehicleDetailModal.vue | P1 |

---

## Appendix: Audited Files

| Fájl | Sorok | Tartalom |
|------|-------|----------|
| backend/app/api/v1/endpoints/vehicles.py | 1-143 | ❌ Csak social ratings, NEM vehicle CRUD |
| backend/app/api/v1/endpoints/assets.py | 1-1231 | ✅ Valódi vehicle CRUD |
| backend/app/schemas/asset.py | 1-453 | ✅ AssetCreate, AssetUpdate, AssetResponse |
| backend/app/schemas/vehicle.py | 1-56 | ❌ Csak social rating sémák |
| backend/app/models/vehicle/asset.py | 1-515 | ✅ Asset modell a 6 új mezővel |
| backend/app/services/asset_service.py | 1-802 | ✅ create_or_claim_vehicle (hiányzó 6 mező) |
| backend/app/api/v1/endpoints/finance_admin.py | 1-77 | ❌ Csak Issuer management |
| backend/app/api/v1/endpoints/expenses.py | 1-418 | ✅ AssetCost CRUD (de nem fleet finance) |
| backend/app/schemas/finance.py | 1-43 | ❌ Csak Issuer sémák |
| backend/app/schemas/fleet.py | 1-20 | ❌ Minimális (EventCreate, TCOStats) |
| backend/app/models/fleet_finance/models.py | 1-286 | ✅ 4 fleet finance modell (API nélkül) |

---

*Ez a report egy read-only audit eredménye. Kódmódosítás nem történt. A frontend redesign csak az Architect jóváhagyása után kezdődhet.*