service-finder/docs/odometer_duplication_audit.md

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

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.