Stuff

backend/src/features/fuel-logs/README.md

@@ -22,13 +22,14 @@ All endpoints require valid JWT token with user context.
 POST /api/fuel-logs
 {
   "vehicleId": "uuid-vehicle-id",
-  "date": "2024-01-15",
-  "odometer": 52000,
-  "gallons": 12.5,
-  "pricePerGallon": 3.299,
-  "totalCost": 41.24,
-  "station": "Shell Station",
-  "location": "123 Main St, City, ST",
+  "dateTime": "2024-01-15T10:30:00Z",
+  "odometerReading": 52000,
+  "tripDistance": 325,
+  "fuelType": "gasoline",
+  "fuelGrade": "premium",
+  "fuelUnits": 12.5,
+  "costPerUnit": 3.299,
+  "locationData": "123 Main St, City, ST",
   "notes": "Full tank, premium gas"
 }
 
@@ -36,16 +37,19 @@ Response (201):
 {
   "id": "uuid-here",
   "userId": "user-id",
-  "vehicleId": "uuid-vehicle-id", 
-  "date": "2024-01-15",
-  "odometer": 52000,
-  "gallons": 12.5,
-  "pricePerGallon": 3.299,
+  "vehicleId": "uuid-vehicle-id",
+  "dateTime": "2024-01-15T10:30:00Z",
+  "odometerReading": 52000,
+  "tripDistance": 325,
+  "fuelType": "gasoline",
+  "fuelGrade": "premium",
+  "fuelUnits": 12.5,
+  "costPerUnit": 3.299,
   "totalCost": 41.24,
-  "station": "Shell Station",
-  "location": "123 Main St, City, ST",
+  "locationData": "123 Main St, City, ST",
   "notes": "Full tank, premium gas",
-  "mpg": 28.4, // Auto-calculated from previous log
+  "efficiency": 28.4, // Auto-calculated from distance/fuelUnits
+  "efficiencyLabel": "MPG",
   "createdAt": "2024-01-15T10:30:00Z",
   "updatedAt": "2024-01-15T10:30:00Z"
 }
@@ -57,13 +61,17 @@ GET /api/fuel-logs/vehicle/:vehicleId/stats
 
 Response (200):
 {
-  "totalLogs": 15,
-  "totalGallons": 187.5,
+  "logCount": 15,
+  "totalFuelUnits": 187.5,
   "totalCost": 618.45,
-  "averageMpg": 29.2,
-  "averagePricePerGallon": 3.299,
-  "lastFillUp": "2024-01-15",
-  "milesTracked": 5475
+  "averageCostPerUnit": 3.299,
+  "totalDistance": 5475,
+  "averageEfficiency": 29.2,
+  "unitLabels": {
+    "distance": "miles",
+    "fuelUnits": "gallons",
+    "efficiencyUnits": "MPG"
+  }
 }
 ```
 
@@ -95,11 +103,12 @@ fuel-logs/
 
 ## Key Features
 
-### MPG Calculation
-- **Auto-calculation**: Computes MPG based on odometer difference from previous log
-- **First Entry**: No MPG for first fuel log (no baseline)
-- **Accuracy**: Requires consistent odometer readings
-- **Validation**: Ensures odometer readings increase over time
+### Efficiency Calculation (MPG/L equivalent)
+- **Auto-calculation**: Computes efficiency based on trip distance or odometer difference
+- **Unit System**: Respects user preference (imperial = MPG, metric = L/100km)
+- **First Entry**: No efficiency for first fuel log (no baseline)
+- **Accuracy**: Requires either trip distance or consistent odometer readings
+- **Validation**: Ensures positive values and proper fuel unit tracking
 
 ### Database Schema
 - **Primary Table**: `fuel_logs` with foreign key to vehicles
@@ -119,10 +128,12 @@ fuel-logs/
 - **Odometer Logic**: Reading must be >= previous reading for same vehicle
 - **Date Validation**: No fuel logs in future (beyond today)
 
-### MPG Calculation Logic
-- **Formula**: (Current Odometer - Previous Odometer) / Gallons
-- **Baseline**: Requires at least 2 fuel logs for calculation
-- **Edge Cases**: Handles first log, odometer resets, missing data
+### Efficiency Calculation Logic
+- **Primary Formula**: Trip Distance / Fuel Units (gives MPG for imperial, L/100km for metric)
+- **Fallback Formula**: (Current Odometer - Previous Odometer) / Fuel Units
+- **Unit Conversion**: Automatically converts between imperial and metric based on user preference
+- **Edge Cases**: Handles first log, odometer resets, missing trip distance data
+- **Aggregation**: Vehicle statistics compute average efficiency across all logs
 
 ## Dependencies
 
@@ -142,15 +153,21 @@ fuel-logs/
 
 ## Caching Strategy
 
-### User Fuel Logs (5 minutes)
-- **Key**: `fuel-logs:user:{userId}`
+### User Fuel Logs (5 minutes per unit system)
+- **Key**: `fuel-logs:user:{userId}:{unitSystem}`
+- **TTL**: 300 seconds (5 minutes)
+- **Invalidation**: On create, update, delete
+- **Unit System**: Cache keys include `imperial` or `metric` for user preference
+
+### Vehicle Fuel Logs (5 minutes per unit system)
+- **Key**: `fuel-logs:vehicle:{vehicleId}:{unitSystem}`
 - **TTL**: 300 seconds (5 minutes)
 - **Invalidation**: On create, update, delete
 
-### Vehicle Statistics (15 minutes)
-- **Key**: `fuel-stats:vehicle:{vehicleId}`
-- **TTL**: 900 seconds (15 minutes)
-- **Rationale**: Stats change less frequently than individual logs
+### Vehicle Statistics
+- **Strategy**: Fresh queries on each request (no caching)
+- **Calculation**: Real-time aggregation of all logs, efficiency calculations
+- **Performance**: Optimized query patterns for vehicle-specific lookups
 
 ## Testing