frontend költség beállítások
This commit is contained in:
Roo
204
docs/p0_backend_api_audit_vehicle_finance_2026-06-21.md
Normal file
204
docs/p0_backend_api_audit_vehicle_finance_2026-06-21.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 🏗️ 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.*
|
||||
Reference in New Issue
Block a user