kincses/service-finder
1
0
Fork 0
Code Issues 52 Pull Requests Packages Projects 2 Releases Wiki Activity
Files
main
service-finder/docs/p0_backend_api_audit_vehicle_finance_2026-06-21.md
Roo 71ef33bb85 frontend költség beállítások
2026-06-23 21:11:21 +00:00

11 KiB
Raw Permalink Blame History

🏗️ 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 View Git Blame Copy Permalink