190 lines
7.5 KiB
Markdown
190 lines
7.5 KiB
Markdown
# 🏛️ 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.
|