first commit
This commit is contained in:
@@ -0,0 +1,325 @@
|
||||
# TankStopp - Fuel Tracking Web Application
|
||||
|
||||
A simple and intuitive web application built with Go to track your fuel station stops and monitor fuel consumption.
|
||||
|
||||
## Features
|
||||
|
||||
- 📊 **Dashboard** - Overview of all fuel stops with statistics
|
||||
- ➕ **Add Fuel Stops** - Record new fuel purchases with detailed information
|
||||
- ✏️ **Edit/Delete** - Modify or remove existing fuel stop records
|
||||
- 📈 **Statistics** - Track total spending, consumption, and average prices
|
||||
- 🛣️ **Trip Length Tracking** - Record distance traveled for accurate consumption calculation
|
||||
- 🔍 **Advanced Filtering** - Filter by date range, fuel type, and location
|
||||
- 📊 **Monthly Reports** - Detailed monthly fuel consumption analytics
|
||||
- 💾 **Bulk Operations** - Import/export multiple fuel stops efficiently
|
||||
- 🔌 **REST API** - JSON endpoints for programmatic access
|
||||
- 🗄️ **GORM Database** - Modern ORM with optimized queries and relationships
|
||||
- 📱 **Responsive Design** - Works on desktop and mobile devices
|
||||
- 📍 **Nearby Stations** - Find fuel stations near your location using OpenStreetMap
|
||||
- ⚙️ **User Settings** - Manage profile, change password, and account preferences
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Go 1.21 or higher
|
||||
- SQLite3 (automatically managed by GORM)
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone or download the project:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd tankstopp
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
3. Run the application:
|
||||
```bash
|
||||
go run cmd/main.go
|
||||
```
|
||||
|
||||
4. Open your browser and navigate to:
|
||||
```
|
||||
http://localhost:8080
|
||||
```
|
||||
|
||||
### Building for Production
|
||||
|
||||
To build a standalone executable:
|
||||
|
||||
```bash
|
||||
go build -o tankstopp cmd/main.go
|
||||
./tankstopp
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Adding a Fuel Stop
|
||||
|
||||
1. Click "Add New Stop" on the dashboard
|
||||
2. Fill in the form with:
|
||||
- Date of the fuel stop
|
||||
- Station name and location
|
||||
- Fuel type (Super E5, E10, Diesel, etc.)
|
||||
- Amount of fuel in liters
|
||||
- Price per liter
|
||||
- Total price (calculated automatically)
|
||||
- Odometer reading (optional)
|
||||
- Notes (optional)
|
||||
|
||||
### Viewing Statistics
|
||||
|
||||
The dashboard shows:
|
||||
- Total number of fuel stops
|
||||
- Total liters purchased
|
||||
- Total amount spent
|
||||
- Average price per liter
|
||||
- Average fuel consumption (if odometer readings are provided)
|
||||
|
||||
### Editing Fuel Stops
|
||||
|
||||
- Click the "Edit" button on any fuel stop card
|
||||
- Modify the information and save
|
||||
|
||||
### Deleting Fuel Stops
|
||||
|
||||
- Click the "Delete" button on any fuel stop card
|
||||
- Confirm the deletion
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The application provides REST API endpoints for integration:
|
||||
|
||||
### GET /api/fuel-stops
|
||||
Returns all fuel stops as JSON.
|
||||
|
||||
**Query Parameters:**
|
||||
- `limit` - Number of results per page (default: 50)
|
||||
- `offset` - Number of results to skip for pagination
|
||||
- `fuel_type` - Filter by fuel type (e.g., "Diesel", "Super E5")
|
||||
- `start_date` - Filter from date (YYYY-MM-DD format)
|
||||
- `end_date` - Filter to date (YYYY-MM-DD format)
|
||||
|
||||
### POST /api/fuel-stops
|
||||
Creates a new fuel stop from JSON data.
|
||||
|
||||
Example request body:
|
||||
```json
|
||||
{
|
||||
"date": "2024-01-15",
|
||||
"station_name": "Shell",
|
||||
"location": "Hamburg",
|
||||
"fuel_type": "Super E5",
|
||||
"liters": 45.5,
|
||||
"price_per_l": 1.599,
|
||||
"total_price": 72.75,
|
||||
"currency": "EUR",
|
||||
"odometer": 125000,
|
||||
"trip_length": 520.5,
|
||||
"notes": "Highway stop"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/stats
|
||||
Returns fuel consumption statistics as JSON.
|
||||
|
||||
### GET /api/stats/monthly/{year}
|
||||
Returns monthly statistics for the specified year.
|
||||
|
||||
### POST /api/fuel-stops/bulk
|
||||
Creates multiple fuel stops in a single transaction.
|
||||
|
||||
## Database
|
||||
|
||||
The application uses **GORM** (Go Object-Relational Mapping) with SQLite3, which creates a `fuel_stops.db` file in the project directory. The database features include:
|
||||
|
||||
### Schema
|
||||
- `users` table with authentication and user preferences
|
||||
- `fuel_stops` table with all fuel stop information
|
||||
- **Foreign key constraints** with cascade delete
|
||||
- **Automatic indexing** on frequently queried fields
|
||||
- **Unique constraints** on usernames and emails
|
||||
|
||||
### Features
|
||||
- **Auto-migration** - Schema updates are handled automatically
|
||||
- **Connection pooling** - Optimized database connections
|
||||
- **Transaction support** - ACID compliance for data integrity
|
||||
- **Relationship management** - Efficient joins and preloading
|
||||
- **Type safety** - Compile-time validation of database operations
|
||||
|
||||
### Performance Optimizations
|
||||
- Prepared statements for faster query execution
|
||||
- Batch operations for bulk inserts
|
||||
- Optimized indexes for common query patterns
|
||||
- Connection pool tuning for concurrent access
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
tankstopp/
|
||||
├── cmd/
|
||||
│ └── main.go # Application entry point
|
||||
├── internal/
|
||||
│ ├── auth/
|
||||
│ │ └── session.go # Session management
|
||||
│ ├── currency/
|
||||
│ │ └── currency.go # Multi-currency support
|
||||
│ ├── database/
|
||||
│ │ └── db.go # GORM database operations
|
||||
│ ├── handlers/
|
||||
│ │ └── handlers.go # HTTP handlers & authentication
|
||||
│ └── models/
|
||||
│ └── fuelstop.go # GORM data models
|
||||
├── templates/
|
||||
│ ├── base.html # Base template
|
||||
│ ├── index.html # Dashboard
|
||||
│ ├── add.html # Add fuel stop form
|
||||
│ └── edit.html # Edit fuel stop form
|
||||
├── static/ # Static files (CSS, JS, images)
|
||||
├── go.mod # Go module definition
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Technologies Used
|
||||
|
||||
- **Backend**: Go with Gorilla Mux for routing
|
||||
- **Database**: GORM ORM with SQLite3
|
||||
- **Authentication**: Session-based with bcrypt password hashing
|
||||
- **Currency**: Multi-currency support with 25+ currencies
|
||||
- **Frontend**: HTML5, Tabler UI framework, Font Awesome
|
||||
- **Templates**: Go HTML templates with custom functions
|
||||
|
||||
## Consumption Tracking Excellence
|
||||
|
||||
### Advanced Trip Analysis
|
||||
TankStopp provides industry-leading fuel consumption tracking with precise trip-based calculations:
|
||||
|
||||
- **Trip Length Input**: Record exact distance traveled since last fillup
|
||||
- **Automatic Consumption Calculation**: Real-time L/100km calculation per trip
|
||||
- **Efficiency Ratings**: Categorized efficiency scoring (Excellent, Good, Average, High, Very High)
|
||||
- **Driving Pattern Recognition**: Highway vs city vs mixed driving analysis
|
||||
- **Fuel Type Optimization**: Compare efficiency across different fuel grades
|
||||
- **Improvement Suggestions**: Identify potential efficiency gains
|
||||
|
||||
### Consumption Metrics
|
||||
- **Individual Trip Consumption**: L/100km for each fuel stop
|
||||
- **Overall Average Consumption**: Weighted average across all trips
|
||||
- **Fuel Type Comparison**: Efficiency by fuel grade (E5, E10, Diesel, etc.)
|
||||
- **Seasonal Analysis**: Monthly consumption trend tracking
|
||||
- **Best/Worst Trip Identification**: Performance benchmarking
|
||||
- **Cost Efficiency**: Cost per kilometer analysis
|
||||
|
||||
### Dual Calculation Methods
|
||||
1. **Primary**: Trip length-based calculation (most accurate)
|
||||
2. **Fallback**: Odometer difference calculation (backward compatibility)
|
||||
3. **Hybrid**: Combines both methods for comprehensive analysis
|
||||
|
||||
## Features in Detail
|
||||
|
||||
### User Management
|
||||
- Secure user registration and authentication
|
||||
- Session-based login with automatic logout
|
||||
- Multi-currency support with user preferences
|
||||
- Password hashing with bcrypt
|
||||
|
||||
### Fuel Stop Tracking
|
||||
- Record date, station, location, fuel type
|
||||
- Track liters purchased and prices with precise decimal storage
|
||||
- Multi-currency support with automatic formatting
|
||||
- Calculate total costs automatically
|
||||
- **Trip length tracking** for accurate fuel consumption calculation
|
||||
- Optional odometer readings for additional tracking
|
||||
- **Individual trip consumption display (L/100km)**
|
||||
- **Real-time consumption analysis** with efficiency ratings
|
||||
- **Per-trip fuel efficiency comparison** across different driving conditions
|
||||
- **Fuel type consumption analysis** (highway vs city vs mixed driving)
|
||||
- Bulk import/export capabilities
|
||||
|
||||
### Advanced Filtering & Search
|
||||
- Filter by date range (start/end dates)
|
||||
- Filter by fuel type (Diesel, Super E5, E10, etc.)
|
||||
- Filter by location or station name
|
||||
- Pagination support for large datasets
|
||||
|
||||
### Statistics Dashboard
|
||||
- Visual overview of fuel consumption patterns
|
||||
- Total spending and volume tracking across currencies
|
||||
- Average price monitoring with trend analysis
|
||||
- **Enhanced fuel consumption calculation** using trip length data
|
||||
- **Per-trip consumption analysis** with efficiency ratings
|
||||
- **Best/worst efficiency trip identification** with improvement suggestions
|
||||
- **Fuel type consumption comparison** across different fuel grades
|
||||
- **Driving pattern analysis** (highway vs city efficiency)
|
||||
- **Monthly consumption trends** with seasonal analysis
|
||||
- **Cost-per-kilometer tracking** for budget planning
|
||||
- Monthly statistics and reports
|
||||
- Last fillup information with trip details
|
||||
|
||||
### Data Management
|
||||
- Create, read, update, delete fuel stops with ACID transactions
|
||||
- Form validation and comprehensive error handling
|
||||
- Responsive design optimized for mobile use
|
||||
- Database relationship management
|
||||
- Automatic schema migrations
|
||||
|
||||
### Nearby Fuel Stations
|
||||
- **Location-based search** using browser geolocation
|
||||
- **OpenStreetMap integration** for real-world fuel station data
|
||||
- **Distance calculation** showing stations within 5km radius
|
||||
- **One-click selection** to auto-fill station name and address
|
||||
- **Smart sorting** by distance from your current location
|
||||
- **Detailed information** including brand, operator, and full address
|
||||
- **Privacy-focused** - location data is only used locally, not stored
|
||||
|
||||
### User Settings
|
||||
- **Profile Management** - Update email address and base currency preference
|
||||
- **Password Security** - Change password with current password verification
|
||||
- **Account Statistics** - View total stops, liters, spending, and consumption
|
||||
- **Currency Preferences** - Set default currency for new fuel stops
|
||||
- **Account Information** - See member since date and account details
|
||||
- **Data Management** - Permanently delete account and all associated data
|
||||
- **Session Security** - Secure password updates with validation
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests if applicable
|
||||
5. Submit a pull request
|
||||
|
||||
## Development
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Enable detailed database logging
|
||||
export DB_DEBUG=true
|
||||
|
||||
# Set environment
|
||||
export ENV=development
|
||||
```
|
||||
|
||||
### Database Development
|
||||
The application uses GORM for database operations. Key features:
|
||||
- **Auto-migration**: Schema updates are automatic
|
||||
- **Query logging**: Enable with `DB_DEBUG=true`
|
||||
- **Connection pooling**: Optimized for performance
|
||||
- **Transaction support**: Automatic rollback on errors
|
||||
|
||||
### Performance Monitoring
|
||||
- Health check endpoint available
|
||||
- Connection pool metrics
|
||||
- Query performance logging in debug mode
|
||||
|
||||
## License
|
||||
|
||||
This project is open source and available under the MIT License.
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions, please create an issue in the project repository.
|
||||
Reference in New Issue
Block a user