8.8 KiB
Trip Length and Consumption Calculation Feature
Overview
The Trip Length feature enhances TankStopp's fuel tracking capabilities by adding distance-based consumption calculations. This feature allows users to track fuel efficiency (L/100km) and provides detailed consumption analytics for better fuel management.
Key Features
1. Trip Length Tracking
- Manual entry of distance traveled since last fill-up
- Automatic calculation based on odometer readings
- Integration with fuel stop records
- Validation for realistic values
2. Consumption Calculations
- Real-time fuel efficiency calculation (L/100km)
- Individual trip consumption tracking
- Average consumption statistics
- Best efficiency tracking
- Efficiency trend analysis
3. Enhanced Dashboard Analytics
- Total distance driven
- Fuel efficiency trends
- Personal best efficiency records
- Consumption-based insights
User Interface Enhancements
Form Fields
Add/Edit Fuel Stop Forms:
- New "Trip Length" input field with km units
- Positioned alongside odometer and total cost fields
- Optional field with smart validation
- Auto-calculation from odometer differences
Dashboard Statistics:
- Enhanced statistics cards showing:
- Total Distance driven
- Efficiency Trend (Improving/Stable/Declining)
- Best Efficiency achieved
- Extended fuel stops table with:
- Trip Length column
- Consumption column (L/100km)
Automatic Features
Smart Trip Length Calculation:
// Automatically calculates trip length when:
// 1. User enters current odometer reading
// 2. Previous odometer reading exists for the vehicle
// 3. Current reading is higher than previous
if (currentOdometer > lastOdometer) {
tripLength = currentOdometer - lastOdometer;
}
Local Storage Integration:
- Stores last odometer reading per vehicle
- Enables automatic trip length calculation
- Persists across browser sessions
- Vehicle-specific tracking
Consumption Calculations
Individual Trip Consumption
Consumption (L/100km) = (Liters / Trip Length) × 100
Example:
- Fuel Amount: 45 liters
- Trip Length: 600 km
- Consumption: (45 / 600) × 100 = 7.5 L/100km
Average Consumption
Calculated from all trips with valid trip length data:
Average = Sum of all consumption readings / Number of trips
Overall Consumption
Total fuel divided by total distance:
Overall = (Total Liters / Total Distance) × 100
Efficiency Trend Analysis
Compares recent fuel stops vs. older stops:
- Improving: Recent consumption is 0.5+ L/100km lower
- Stable: Difference is within ±0.5 L/100km
- Declining: Recent consumption is 0.5+ L/100km higher
Validation Rules
Trip Length Validation
- Minimum: 0 km (optional field)
- Maximum: 2000 km (prevents unrealistic entries)
- Type: Decimal with 0.1 km precision
Consumption Validation
When both trip length and fuel amount are provided:
- Minimum: 1.0 L/100km (prevents unrealistic efficiency)
- Maximum: 50.0 L/100km (catches data entry errors)
Error Messages:
"Fuel consumption 75.2 L/100km seems unrealistic. Please check trip length and amount"
"Fuel consumption 0.3 L/100km seems too low. Please check trip length and amount"
Dashboard Analytics
Statistics Cards
1. Average Consumption Card
- Shows calculated L/100km instead of basic liters
- Updates based on trip length data
- Falls back to basic stats if no trip data
2. Total Distance Card
- Sums all recorded trip lengths
- Shows kilometers driven with tracked data
- Progress indicator for tracking coverage
3. Efficiency Trend Card
- Analyzes recent vs. historical performance
- Color-coded indicators:
- 🟢 Green: Improving efficiency
- 🔵 Blue: Stable performance
- 🔴 Red: Declining efficiency
4. Best Efficiency Card
- Tracks personal best consumption reading
- Motivational element for users
- Filters out unrealistic values
Enhanced Fuel Stops Table
New Columns:
- Trip Length: Distance in km, "Not recorded" if empty
- Consumption: Calculated L/100km, "N/A" if no trip length
Example Table Row:
Date | Vehicle | Amount | Trip Length | Consumption
2024-01-15 | My Car | 42.5 L | 580 km | 7.3 L/100km
2024-01-10 | My Car | 38.2 L | - | N/A
Technical Implementation
Database Schema
The trip_length field already exists in the FuelStop model:
type FuelStop struct {
// ... other fields
TripLength float64 `json:"trip_length" gorm:"default:0;type:decimal(8,2)"`
}
Form Processing
Enhanced form parsing includes trip length:
form := models.FuelStopForm{
// ... other fields
TripLength: parseFloat(r.FormValue("trip_length")),
}
Calculation Functions
func calculateConsumptionStats(stops []models.FuelStop) (float64, float64, float64) {
// Returns: avgConsumption, overallConsumption, totalKm
}
func calculateEfficiencyTrend(stops []models.FuelStop) string {
// Returns: "improving", "stable", "worsening", or "insufficient_data"
}
JavaScript Integration
Client-side features:
- Automatic trip length calculation
- Real-time form validation
- Local storage management
- Currency and unit formatting
Usage Guide
Adding Trip Length Data
Option 1: Manual Entry
- Navigate to "Add Fuel Stop" form
- Enter trip length in the "Trip Length" field
- System calculates consumption automatically
Option 2: Odometer-Based Calculation
- Enter current odometer reading
- If previous reading exists, trip length auto-calculates
- Review and adjust if needed
- System stores reading for next calculation
Viewing Consumption Data
Dashboard Overview:
- Check efficiency trend in statistics cards
- Review total distance driven
- Monitor personal best efficiency
Detailed Analysis:
- View consumption for each trip in the fuel stops table
- Compare efficiency across different vehicles
- Track improvement over time
Best Practices
Data Entry:
- Enter odometer readings consistently for automatic calculation
- Verify trip length seems reasonable for the time period
- Record trip length for highway vs. city driving analysis
Monitoring:
- Check efficiency trends monthly
- Compare consumption across different fuel types
- Use best efficiency as improvement goal
Benefits
For Users
- Better Fuel Management: Track actual consumption vs. estimates
- Cost Optimization: Identify most efficient driving patterns
- Vehicle Comparison: Compare efficiency across multiple vehicles
- Trend Awareness: Spot changes in fuel efficiency over time
For Fleet Management
- Driver Performance: Monitor fuel efficiency by driver/vehicle
- Route Optimization: Identify most fuel-efficient routes
- Maintenance Alerts: Declining efficiency may indicate service needs
- Cost Analysis: Detailed consumption reporting
Future Enhancements
Planned Features
- Route Integration: GPS-based automatic trip length calculation
- Efficiency Goals: Set and track fuel efficiency targets
- Comparative Analytics: Compare against vehicle manufacturer specs
- Export Features: Consumption reports for tax/business purposes
API Extensions
- Consumption Endpoints: Dedicated API for efficiency data
- Trend Analysis: Historical consumption pattern APIs
- Vehicle Comparison: Cross-vehicle efficiency comparisons
Troubleshooting
Common Issues
Trip Length Not Calculating:
- Ensure odometer readings are entered consistently
- Check that current reading is higher than previous
- Verify vehicle selection is correct
Unrealistic Consumption Values:
- Review trip length for accuracy
- Check fuel amount for typos
- Consider if driving conditions affected efficiency
Missing Consumption Data:
- Trip length must be > 0 for consumption calculation
- Historical data without trip length shows "N/A"
- Gradual data collection improves accuracy over time
Data Migration
Existing fuel stops without trip length:
- Show "Not recorded" in trip length column
- Display "N/A" for consumption
- No impact on other functionality
- Users can edit historical entries to add trip length
Summary
The Trip Length and Consumption feature transforms TankStopp from basic fuel tracking to comprehensive efficiency monitoring. By combining distance data with fuel consumption, users gain valuable insights into their driving efficiency and can make informed decisions about fuel usage and vehicle performance.
The feature integrates seamlessly with existing functionality while providing powerful new analytics capabilities, making TankStopp a complete fuel management solution.
Feature Version: 1.0
Implementation Date: January 2024
Compatibility: All existing fuel stop data
Performance Impact: Minimal (calculations are lightweight)
User Impact: Enhanced analytics and insights