service-finder/docs/p0_financial_data_modeling_audit_2026-06-20.md

🏛️ P0 AUDIT: Financial Data Modeling - Purchasing, Leasing, Insurance & Taxes

Dátum: 2026-06-20 Szerző: Rendszer-Architect Státusz: AUDIT COMPLETE (no code changes) Hatáskör: backend/app/models/vehicle/asset.py, backend/app/models/vehicle/vehicle.py

---

1. AssetFinancials Audit

1.1 Jelenlegi állapot

A AssetFinancials modell a vehicle.asset_financials táblában egy 1:1 kapcsolatban áll az Asset modelllel (uselist=False).

Meglévő oszlopok:

Oszlop	Típus	Leírás
id	Integer PK	Elsődleges kulcs
asset_id	UUID FK → vehicle.assets.id	UNIQUE - 1:1 kapcsolat
purchase_price_net	Numeric(18,2)	Nettó vételár
purchase_price_gross	Numeric(18,2)	Bruttó vételár
vat_rate	Numeric(5,2)	ÁFA kulcs (alapértelmezett: 27.00)
activation_date	DateTime	Aktiválás dátuma
verified_purchase_date	DateTime	Ellenőrzött vásárlás dátuma
financing_type	String(50)	Finanszírozás típusa (pl. cash, loan, lease, unknown)
accounting_details	JSONB	Könyvelési részletek (catch-all)

1.2 Hiányzó mezők (lízing/hitel finanszírozáshoz)

A következő mezők hiányoznak a jelenlegi modellből:

Hiányzó mező	Típus	Indoklás
down_payment	Numeric(18,2)	Előleg - lízing és hitel esetén kritikus
monthly_installment	Numeric(18,2)	Havi törlesztő részlet
residual_value	Numeric(18,2)	Maradványérték (lízing végén)
contract_number	String(100)	Szerződésszám (hitel/lízing szerződés)
financing_provider	String(200)	Finanszírozó neve (bank, lízingcég)
interest_rate	Numeric(5,2)	Kamatláb (%)
total_contract_value	Numeric(18,2)	Teljes szerződéses érték
lease_start_date	DateTime	Lízing kezdő dátuma
lease_end_date	DateTime	Lízing vége dátuma
payment_frequency	String(20)	Fizetési gyakoriság (monthly/quarterly/yearly)
payment_day	Integer	Fizetési nap a hónapban (1-28)

1.3 Javasolt bővítés

A meglévő accounting_details JSONB mező alkalmas lehet könyvelési metaadatok tárolására, de dedikált oszlopok szükségesek a lekérdezhetőség és adatintegritás biztosításához.

Javasolt új mezők az AssetFinancials modellhez:

• down_payment - Előleg
• monthly_installment - Havi törlesztő
• residual_value - Maradványérték
• contract_number - Szerződésszám
• financing_provider - Finanszírozó neve
• interest_rate - Kamatláb
• total_contract_value - Teljes szerződéses érték
• lease_start_date - Lízing kezdete
• lease_end_date - Lízing vége
• payment_frequency - Fizetési gyakoriság
• payment_day - Fizetési nap

---

2. Cost & Expense Modellek Összehasonlítása

2.1 VehicleExpenses - Legacy modell

Tulajdonság	Érték
Tábla	vehicle.vehicle_expenses
Kategória típusa	String(50) - egyszerű string, nincs FK
ÁFA kezelés	Nincs
Jóváhagyási workflow	Nincs
Számla/dokumentum	Nincs
Kapcsolat AssetEvent-tel	Nincs
Használat	Legacy, egyszerű reporting

2.2 AssetCost - Elsődleges költségmodell

Tulajdonság	Érték
Tábla	vehicle.asset_costs
Kategória	category_id → vehicle.cost_categories (FK)
ÁFA kezelés	amount_net, amount_gross, vat_rate (Gross-First)
Jóváhagyási workflow	DRAFT → PENDING_APPROVAL → APPROVED
Számla/dokumentum	invoice_number, document_id
Smart Sync (AssetEvent)	Bidirectional linked_asset_event_id
JSONB adatok	Extra mezők: mileage_at_cost, description
Szervezeti kötés	organization_id

2.3 Következtetés

A VehicleExpenses egy legacy, leegyszerűsített modell, amelyet a jövőben fokozatosan ki kell vezetni. A AssetCost a teljes értékű, jóváhagyási workflow-val és Smart Sync-kel rendelkező költségmodell.

---

3. Adatbázis Stratégia - Javasolt Rétegek

3.1 Rétegdiagram

1. réteg: Beszerzés & Finanszírozás (AssetFinancials)
  ├─ purchase_price_net / purchase_price_gross / vat_rate
  ├─ down_payment / monthly_installment / residual_value
  ├─ contract_number / financing_provider / interest_rate
  ├─ lease_start_date / lease_end_date
  └─ payment_frequency / payment_day

2. réteg: Működési költségek (AssetCost)
  ├─ category_id → CostCategory
  ├─ amount_net / amount_gross / vat_rate
  ├─ invoice_number / status
  └─ linked_asset_event_id / data JSONB

3. réteg: Biztosítási kötvények (VehicleInsurancePolicy) - ÚJ
  ├─ policy_number / insurer_name / coverage_type
  ├─ coverage_limit / deductible
  ├─ start_date / end_date / renewal_status
  └─ premium_amount

4. réteg: Adókötelezettségek (VehicleTaxObligation) - ÚJ
  ├─ tax_type / authority / assessment_period
  ├─ tax_amount / due_date
  └─ payment_status / exemption_status

3.2 Stratégia összefoglalása

1. réteg - AssetFinancials bővítése:

• Egyszeri beszerzési adatok: vételár, áfa, aktiválás dátuma
• Finanszírozási adatok: előleg, havi törlesztő, maradványérték, futamidő, kamatláb, szerződésszám
• 1:1 kapcsolatban az Asset-tel

2. réteg - AssetCost (már létezik, változtatás nélkül):

• Minden operatív költség itt landol: szerviz, üzemanyag, biztosítási díj befizetések, adó befizetések
• Jóváhagyási workflow (DRAFT → APPROVED)

3. réteg - VehicleInsurancePolicy (ÚJ modell javasolt):

• A biztosítási kötvény metaadatai
• A díj befizetések az AssetCost-ban rögzítésre kerülnek

4. réteg - VehicleTaxObligation (ÚJ modell javasolt):

• Az adókötelezettség metaadatai
• A díj befizetések az AssetCost-ban rögzítésre kerülnek

3.3 Döntési fa

Pénzügyi rekord érkezik
│
├─ Egyszeri beszerzési/vásárlási adat?
│  → AssetFinancials
│
├─ Finanszírozási szerződés (lízing/hitel)?
│  → AssetFinancials
│
├─ Rendszeres díj befizetés (biztosítás, adó)?
│  → AssetCost
│
├─ Biztosítási kötvény adatai?
│  → VehicleInsurancePolicy
│
└─ Adókötelezettség adatai?
   → VehicleTaxObligation

---

4. Módosítandó Fájlok (Tervezés - NEM kódolva)

Fájl	Művelet
backend/app/models/vehicle/asset.py	AssetFinancials bővítése lízing/hitel mezőkkel + új VehicleInsurancePolicy + VehicleTaxObligation modellek
backend/app/schemas/asset.py	AssetFinancials Pydantic schema bővítése
backend/app/services/asset_service.py	AssetService.create_or_claim_vehicle() frissítése (jelenleg hardcode 0 érték)
backend/app/api/v1/endpoints/financials.py	Potenciálisan új endpoint a biztosítás/adó CRUD-hoz

---

5. Konklúzió

1. AssetFinancials jelenleg is alkalmas a beszerzési adatok tárolására, de hiányoznak belőle a lízing-specifikus mezők.

2. AssetCost a helyes modell az operatív költségekhez (beleértve a biztosítási díjakat és adó befizetéseket is). A VehicleExpenses legacy modell kivezetendő.

3. Dedikált modellek (VehicleInsurancePolicy, VehicleTaxObligation) szükségesek a biztosítási kötvények és adókötelezettségek metaadatainak tárolásához, míg a tényleges befizetések az AssetCost-ban landolnak.