tankstopp-app/docs/VEHICLE_MANAGEMENT.md

Vehicle Management System

Overview

The TankStopp application now includes a comprehensive vehicle management system that allows users to track fuel consumption and expenses for multiple vehicles. This feature enables users to organize their fuel stops by vehicle and analyze consumption patterns per vehicle.

Features

1. Vehicle CRUD Operations

Create Vehicle

• Add new vehicles with the following information:
  • Vehicle Name (required) - A friendly name to identify the vehicle
  • Make (optional) - e.g., Toyota, BMW, Ford
  • Model (optional) - e.g., Corolla, 3 Series, Focus
  • Year (optional) - Manufacturing year
  • License Plate (optional) - Vehicle registration number
  • Primary Fuel Type (optional) - Super E5, Super E10, Diesel, Electric, etc.
  • Status - Active/Inactive (only active vehicles appear in fuel stop forms)
  • Notes (optional) - Additional information about the vehicle

Read/List Vehicles

• View all vehicles in a card-based layout
• Active vehicles are highlighted with a green "Active" badge
• Inactive vehicles are marked with a gray "Inactive" badge
• Empty state shows when no vehicles exist

Update Vehicle

• Edit all vehicle information
• Toggle vehicle active/inactive status
• Preserve all existing fuel stops when updating

Delete Vehicle

• Delete vehicles with confirmation dialog
• Protection against deleting vehicles with existing fuel stops
• Clear error messages when deletion is not allowed

2. Database Schema

The Vehicle model includes:

type Vehicle struct {
    ID           uint       // Primary key
    UserID       uint       // Foreign key to User
    Name         string     // Required, max 100 chars
    Make         string     // Optional, max 50 chars
    Model        string     // Optional, max 50 chars
    Year         int        // Optional, valid range: 1900-current year+1
    LicensePlate string     // Optional, max 20 chars
    FuelType     string     // Optional, max 50 chars
    Notes        string     // Optional, text field
    IsActive     bool       // Default: true
    FuelStops    []FuelStop // One-to-many relationship
    CreatedAt    time.Time
    UpdatedAt    time.Time
}

3. User Interface

Navigation

• "Vehicles" link added to the main navigation menu in all pages
• Accessible from Dashboard, Add Stop, Edit Stop, and Settings pages

Vehicles List Page (/vehicles)

• Card-based layout showing all user vehicles
• Each card displays:
  • Vehicle name with car icon
  • Active/Inactive status badge
  • Vehicle details (Make, Model, Year, License Plate, Fuel Type)
  • Notes (if any)
  • Edit and Delete action buttons
• "Add Vehicle" button in the navbar
• Success/Error alerts for user feedback
• Empty state with call-to-action when no vehicles exist

Add Vehicle Page (/vehicles/add)

• Clean form layout with icons for each field
• Real-time year defaulting to current year
• Toggle switch for active/inactive status
• Cancel and Save buttons

Edit Vehicle Page (/vehicles/edit/{id})

• Pre-populated form with existing vehicle data
• Same layout as Add Vehicle page
• Update button instead of Save

4. Integration with Fuel Stops

• Fuel stops are now associated with vehicles
• Vehicle selection dropdown in Add/Edit fuel stop forms
• Only active vehicles appear in the dropdown
• Vehicle information displayed in fuel stop listings

5. API Endpoints

The following routes are available:

• GET /vehicles - List all vehicles for the logged-in user
• GET /vehicles/add - Display add vehicle form
• POST /vehicles/add - Create a new vehicle
• GET /vehicles/edit/{id} - Display edit form for a specific vehicle
• POST /vehicles/edit/{id} - Update a specific vehicle
• POST /vehicles/delete/{id} - Delete a specific vehicle

6. Validation Rules

• Vehicle name is required and must be 100 characters or less
• Make must be 50 characters or less
• Model must be 50 characters or less
• License plate must be 20 characters or less
• Fuel type must be 50 characters or less
• Year must be between 1900 and current year + 1
• User must own the vehicle to edit or delete it
• Cannot delete vehicles with existing fuel stops

7. Security Features

• All vehicle operations require authentication
• Users can only access their own vehicles
• CSRF protection on all forms
• Input validation and sanitization
• SQL injection protection through GORM parameterized queries

Usage Guide

Adding Your First Vehicle

1. Navigate to the "Vehicles" page from the main navigation
2. Click "Add Vehicle" button
3. Enter at least the vehicle name (required)
4. Optionally fill in other details
5. Click "Save Vehicle"

Managing Vehicles

1. From the Vehicles page, you can:
   • View all your vehicles at a glance
   • Click "Edit" to modify vehicle details
   • Click "Delete" to remove a vehicle (only if no fuel stops exist)
   • Toggle active/inactive status when editing

Tracking Fuel by Vehicle

1. When adding a fuel stop, select the appropriate vehicle from the dropdown
2. Only active vehicles will appear in the selection
3. Vehicle information will be stored with each fuel stop for reporting

Future Enhancements

Potential improvements for the vehicle management system:

1. Vehicle Statistics

   • Fuel consumption per vehicle
   • Cost analysis per vehicle
   • Maintenance tracking

2. Vehicle Images

   • Upload and display vehicle photos
   • Default icons based on vehicle type

3. Advanced Features

   • Vehicle sharing between family members
   • Fleet management for businesses
   • Maintenance reminders
   • Insurance and registration tracking

4. Import/Export

   • Import vehicle data from CSV
   • Export vehicle list
   • Backup and restore functionality