# Odometer Rendszer Duplikáció Audit Jelentés

**Dátum:** 2026-06-12
**Auditor:** Rendszer-Architect
**Gitea Issue:** #258

## Összefoglaló

A vizsgálat feltárta, hogy az odometer (kilométeróra) adatok **több helyen és több formában** vannak tárolva a rendszerben, ami duplikációhoz és architekturális inkonzisztenciához vezet.

---

## 1. Összes Odometer-rel Kapcsolatos Elem

### 1.1 Különálló Táblák

| # | Tábla (Schema) | Modell | Fájl | Elsődleges Entitás |
|---|---|---|---|---|
| 1 | `vehicle.odometer_readings` | `OdometerReading` | `backend/app/models/vehicle/asset.py:347` | Asset (járműpéldány) |
| 2 | `vehicle.vehicle_odometer_states` | `VehicleOdometerState` | `backend/app/models/vehicle/vehicle.py:112` | VehicleModelDefinition (katalógus) |
| 3 | `vehicle.asset_telemetry` | `AssetTelemetry` (`current_mileage`) | `backend/app/models/vehicle/asset.py:338` | Asset (járműpéldány) |

### 1.2 Oszlopok Más Táblákban

| # | Tábla | Oszlop | Fájl |
|---|---|---|---|
| 4 | `vehicle.costs` | `odometer` | `backend/app/models/vehicle/vehicle.py:97` |
| 5 | `vehicle.asset_events` | `odometer_reading` | `backend/app/models/vehicle/asset.py:400` |
| 6 | `marketplace.costs` | `odometer_km` | `backend/app/models/marketplace/service.py:172` |

---

## 2. Részletes Elemzés

### 2.1 `OdometerReading` (asset.py:347)
- **Cél:** Km óra állás időbeli nyomonkövetése. Minden egyes leolvasás külön rekord.
- **Adatbázis séma:** `vehicle.odometer_readings(id, asset_id, reading, recorded_at, source, cost_id)`
- **Forrás:** `manual`, `api`, `telemetry`, `cost_entry`
- **Kötődés:** `vehicle.assets` (Asset) - **konkrét járműpéldány**
- **FK:** `odometer_readings_asset_id_fkey` → `vehicle.assets.id`

### 2.2 `VehicleOdometerState` (vehicle.py:112)
- **Cél:** Okos odometer - becsült aktuális km állás, napi átlag, konfidencia score.
- **Adatbázis séma:** `vehicle.vehicle_odometer_states(vehicle_id PK, last_recorded_odometer, last_recorded_date, daily_avg_distance, estimated_current_odometer, confidence_score, manual_override_avg)`
- **Kötődés:** `vehicle.vehicle_model_definitions` (VehicleModelDefinition) - **katalógusrekord**
- **FK:** `vehicle_odometer_states_vehicle_id_fkey` → `vehicle.vehicle_model_definitions.id`
- **Adatforrás:** Kizárólag a `VehicleCost.odometer` mezőből számol (`odometer_service.py:59-62`)

### 2.3 `AssetTelemetry.current_mileage` (asset.py:338)
- **Cél:** Telemetriai adat tárolása.
- **Kötődés:** `vehicle.assets` (Asset) - **konkrét járműpéldány**
- **Nincs integrálva** sem az `OdometerReading`, sem a `VehicleOdometerState` rendszerrel.

### 2.4 `VehicleCost.odometer` (vehicle.py:97)
- **Cél:** Költségbejegyzéshez tartozó km állás (NOT NULL).
- **Kötődés:** `vehicle.vehicle_model_definitions` (VehicleModelDefinition)
- **Funkció:** Ez az adatforrása a `VehicleOdometerState` számításnak.

### 2.5 `AssetEvent.odometer_reading` (asset.py:400)
- **Cél:** Digitális szervizkönyv eseményhez tartozó km állás.
- **Kötődés:** `vehicle.assets` (Asset)
- **Nincs integrálva** semmilyen más odometer rendszerrel.

### 2.6 `marketplace.costs.odometer_km`
- **Cél:** Marketplace szolgáltatás árához tartozó km állás.
- **Teljesen elkülönült** rendszer.

---

## 3. A Duplikáció Leírása

### 3.1 Két Párhuzamos Odometer Rendszer

#### A) Asset-alapú Odometer Rendszer (komplett, de kihasználatlan)
- **Tábla:** `vehicle.odometer_readings`
- **Használat:** Csak `expenses.py:108-127` hoz létre `OdometerReading` rekordot költség rögzítésekor.
- **Kötődés:** `Asset` (konkrét jármű)
- **Státusz:** Létezik, de **nincs kihasználva** a VehicleOdometerState számára.

#### B) Vehicle-definition-alapú Odometer Rendszer (aktív, de hibás)
- **Tábla:** `vehicle.vehicle_odometer_states`
- **Service:** `odometer_service.py` - teljes funkcionalitás
- **Kötődés:** `VehicleModelDefinition` (katalógusrekord)
- **Adatforrás:** `VehicleCost.odometer` (szintén vehicle-definition-hez kötött)
- **Státusz:** Működik, de **architekturálisan hibás**, mert egy katalógusrekordhoz rendel km állást.

### 3.2 Architekturális Következmények

1. **Adatvesztés:** Az Asset-hez tartozó `OdometerReading` adatok nincsenek felhasználva a VehicleOdometerState számításban.
2. **Inkonzisztens adat:** Telemetriából vagy manuális bevitelből származó km adatok nem kerülnek be a VehicleOdometerState-ba.
3. **Entitás zavar:** A `VehicleModelDefinition` egy katalógusrekord, aminek NINCS km óra állása.
4. **Több forrás, nincs szinkron:** AssetTelemetry, OdometerReading, AssetEvent mind Asset-hez kötött, de nincsenek szinkronizálva.

---

## 4. Mermaid Diagram

```mermaid
graph TD
    subgraph "ASSET-alapú (konkrét jármű)"
        A[Asset] --> OR[OdometerReading<br/>vehicle.odometer_readings]
        A --> AT[AssetTelemetry<br/>current_mileage]
        A --> AE[AssetEvent<br/>odometer_reading]
    end

    subgraph "VEHICLE-DEFINITION-alapú (katalógus)"
        VMD[VehicleModelDefinition] --> VOS[VehicleOdometerState<br/>vehicle.vehicle_odometer_states]
        VMD --> VC[VehicleCost<br/>odometer]
    end

    subgraph "SZOLGÁLTATÁS"
        OS[OdometerService<br/>odometer_service.py] -->|számol| VC
        OS -.->|NEM használja| OR
    end

    subgraph "MARKETPLACE (elkülönült)"
        MC[Marketplace Cost<br/>odometer_km]
    end

    style VOS fill:#f96,stroke:#333,stroke-width:2px
    style OR fill:#9cf,stroke:#333,stroke-width:2px
    style OS fill:#ff9,stroke:#333,stroke-width:2px
```

---

## 5. Javaslat

1. A `VehicleOdometerState`-ot át kell kötni az `Asset` entitáshoz.
2. Az `OdometerService`-nek az `OdometerReading` táblából kellene számolnia.
3. Az `AssetTelemetry.current_mileage` és `AssetEvent.odometer_reading` integrálni kell az `OdometerReading` rendszerbe.
4. A `marketplace.costs.odometer_km` egységesítése.