Initial commit: gocarlog project — Milestones 1-10 completed

This commit is contained in:
2026-06-07 11:57:42 +02:00
commit 1d17422093
29 changed files with 4532 additions and 0 deletions
+387
View File
@@ -0,0 +1,387 @@
# GoCarLog - API Spezifikation
Alle API-Endpunkte sind unter `/api/v1/...` erreichbar.
Antwortformat: JSON, Content-Type: `application/json`.
Fehlerantworten haben das Format: `{"error": "Fehlerbeschreibung", "code": 400}`.
---
## 1. Kraftstoffe abrufen
### `GET /api/v1/fuels`
Listet alle Kraftstoffe auf.
**Antwort (200 OK):**
```json
{
"success": true,
"data": [
{ "id": 0, "name": "Diesel", "unit": "L" },
{ "id": 1, "name": "Benzin", "unit": "L" },
{ "id": 2, "name": "LPG", "unit": "L" },
{ "id": 3, "name": "CNG", "unit": "L" },
{ "id": 4, "name": "Strom", "unit": "kWh" }
]
}
```
---
## 2. Fahrzeug anlegen
### `POST /api/v1/vehicles`
Erstellt ein neues Fahrzeug.
**Request Body:**
```json
{
"name": "Mein Auto",
"fuel_id": 0,
"manufacturer": "BMW",
"model": "320d",
"year": 2020,
"description": "Mein BMW 3er",
"license_plate": "AC B 1234",
"purchase_date": "2020-01-15",
"weight_kg": 1500,
"power_kw": 140,
"max_odometer": 300000
}
```
**Pflichtfelder:** `name`, `fuel_id`
**Antwort (201 Created):**
```json
{
"success": true,
"data": {
"id": 1,
"name": "Mein Auto",
"manufacturer": "BMW",
"model": "320d",
"year": 2020,
"description": "Mein BMW 3er",
"license_plate": "AC B 1234",
"purchase_date": "2020-01-15",
"weight_kg": 1500,
"power_kw": 140,
"max_odometer": 300000,
"current_odometer": 0,
"fuel_id": 0,
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
**Fehler (400 Bad Request):**
```json
{
"success": false,
"error": "name und fuel_id sind erforderlich"
}
```
---
## 3. Fahrzeuge auflisten
### `GET /api/v1/vehicles`
Listet Fahrzeuge mit optionalen Filtern auf.
**Query-Parameter:**
| Parameter | Typ | Beschreibung |
|--------------|--------|--------------------------------------|
| `name` | string | Filter nach Name (Substring) |
| `license_plate` | string | Filter nach Kennzeichen |
| `fuel_id` | int | Filter nach Kraftstoff-ID |
| `manufacturer` | string | Filter nach Hersteller (Substring) |
| `model` | string | Filter nach Modell (Substring) |
| `year` | int | Filter nach Baujahr |
| `limit` | int | Maximale Anzahl Ergebnisse (default: 100) |
| `offset` | int | Offset für Pagination (default: 0) |
**Antwort (200 OK):**
```json
{
"success": true,
"data": [
{
"id": 1,
"name": "Mein Auto",
"manufacturer": "BMW",
"model": "320d",
"fuel_name": "Diesel",
"fuel_id": 0,
"power_kw": 140,
"current_odometer": 45230.5
},
{
"id": 2,
"name": "Fahrrad",
"manufacturer": null,
"model": null,
"fuel_name": null,
"fuel_id": null,
"power_kw": null,
"current_odometer": 0
}
],
"total": 2
}
```
---
## 4. Fahrzeugdetails
### `GET /api/v1/vehicles/:id`
Gibt alle Eigenschaften eines Fahrzeugs aus.
**Antwort (200 OK):**
```json
{
"success": true,
"data": {
"id": 1,
"name": "Mein Auto",
"manufacturer": "BMW",
"model": "320d",
"year": 2020,
"description": "Mein BMW 3er",
"license_plate": "AC B 1234",
"purchase_date": "2020-01-15",
"weight_kg": 1500,
"power_kw": 140,
"max_odometer": 300000,
"current_odometer": 45230.5,
"fuel": {
"id": 0,
"name": "Diesel",
"unit": "L"
},
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
**Fehler (404 Not Found):**
```json
{
"success": false,
"error": "Fahrzeug nicht gefunden"
}
```
---
## 5. Logbucheintrag anlegen
### `POST /api/v1/logs`
Erstellt einen neuen Logbucheintrag. Aktualisiert automatisch `current_odometer` im Fahrzeug falls der Kilometerstand höher ist.
**Request Body:**
```json
{
"vehicle_id": 1,
"log_type": "tankung",
"odometer": 46000,
"datetime": "2026-06-06T14:30:00Z",
"fuel_id": 0,
"cost": 65.50,
"quantity": 5.2,
"note": "Volle Tankung an Shell Station"
}
```
**Pflichtfelder:** `vehicle_id`, `log_type`, `odometer`
**Standardwerte:**
- `datetime` → aktuelle Zeit (wenn nicht angegeben)
- `cost` → 0
- `quantity` → 0
- `note` → "" (leer)
**log_type Werte:** `tankung`, `wartung`, `reparatur`, `notiz`
**Antwort (201 Created):**
```json
{
"success": true,
"data": {
"id": 1,
"vehicle_id": 1,
"log_type": "tankung",
"odometer": 46000,
"datetime": "2026-06-06T14:30:00Z",
"fuel_id": 0,
"cost": 65.50,
"quantity": 5.2,
"unit": "L",
"note": "Volle Tankung an Shell Station",
"created_at": "2026-06-06T14:30:00Z"
}
}
```
**Auto-Update Fahrzeug Odometer:**
Wenn `odometer > current_odometer` des Fahrzeugs, wird `current_odometer` automatisch aktualisiert.
**Fehler (400 Bad Request):**
```json
{
"success": false,
"error": "vehicle_id und log_type sind erforderlich"
}
```
**Fehler (404 Not Found):**
```json
{
"success": false,
"error": "Fahrzeug nicht gefunden"
}
```
---
## 6. Logbucheinträge auflisten
### `GET /api/v1/logs`
Listet Logbucheinträge mit Filtern auf.
**Query-Parameter:**
| Parameter | Typ | Beschreibung |
|------------|--------|-----------------------------------|
| `vehicle_id` | int | Filter nach Fahrzeug-ID |
| `log_type` | string | Filter nach Eintragsart |
| `date_from` | string | Startdatum (ISO 8601) |
| `date_to` | string | Enddatum (ISO 8601) |
| `limit` | int | Maximale Anzahl (default: 100) |
| `offset` | int | Offset für Pagination (default: 0) |
**Antwort (200 OK):**
```json
{
"success": true,
"data": [
{
"id": 1,
"vehicle_id": 1,
"vehicle_name": "Mein Auto",
"log_type": "tankung",
"odometer": 46000,
"datetime": "2026-06-06T14:30:00Z",
"fuel": {
"id": 0,
"name": "Diesel",
"unit": "L"
},
"cost": 65.50,
"quantity": 5.2,
"unit": "L",
"consumption_per_100km": "1.42 L/100km",
"note": "Volle Tankung an Shell Station",
"created_at": "2026-06-06T14:30:00Z"
}
],
"summary": {
"total_count": 1,
"cost_by_type": {
"tankung": 65.50,
"wartung": 0,
"reparatur": 0,
"notiz": 0
}
}
}
```
**Berechneter Verbrauch (`consumption_per_100km`):**
- Wird nur für Einträge mit `log_type: "tankung"` berechnet
- Verbrauch = `quantity / (current_odometer - previous_odometer) * 100`
- `previous_odometer` = Odometer des vorherigen Logeintrags (nach datetime sortiert, gleiches Fahrzeug)
- Wenn kein vorheriger Odometer-Wert existiert: Feld wird nicht ausgeliefert (`null`)
- Nicht-Tankungen (Wartung, Reparatur, Notiz) haben diesen Wert nicht
---
## 7. Durchschnittsverbrauch berechnen
### `GET /api/v1/vehicles/:id/consumption`
Berechnet den Durchschnittsverbrauch basierend auf Tankungseinträgen.
**Query-Parameter:**
| Parameter | Typ | Beschreibung |
|-----------|--------|-----------------------------------|
| `date_from` | string | Startdatum (ISO 8601, optional) |
| `date_to` | string | Enddatum (ISO 8601, optional) |
**Antwort (200 OK):**
```json
{
"success": true,
"data": {
"vehicle_id": 1,
"vehicle_name": "Mein Auto",
"fuel_name": "Diesel",
"fuel_unit": "L",
"total_fuel": 156.8,
"total_distance": 12340.5,
"average_consumption": 6.37,
"consumption_unit": "L/100km",
"period": {
"from": "2026-01-01T00:00:00Z",
"to": "2026-06-06T23:59:59Z"
}
}
}
```
**Berechnung:**
- `total_distance` = Summe der Distanzen zwischen aufeinanderfolgenden Tankungen (Differenz der Odometer-Stände)
- `total_fuel` = Summe der getankten Mengen (quantity)
- `average_consumption` = `total_fuel / total_distance * 100` (L/100km)
- Wenn keine ausreichenden Daten vorhanden: `average_consumption: null`
**Fehler (404 Not Found):**
```json
{
"success": false,
"error": "Fahrzeug nicht gefunden"
}
```
---
## Fehler-Handling
Alle Fehlerantworten folgen diesem Muster:
```json
{
"success": false,
"error": "Menschliche Fehlerbeschreibung",
"code": 400
}
```
| HTTP Status | Bedeutung |
|-------------|------------------------------|
| 200 | Erfolg |
| 201 | Erstellt (POST erfolgreich) |
| 400 | Ungültige Eingabe |
| 404 | Ressource nicht gefunden |
| 500 | Interner Serverfehler |
+163
View File
@@ -0,0 +1,163 @@
# GoCarLog - Datenbankstruktur
## Übersicht
GoCarLog verwendet SQLite als eingebettete Datenbank. Das Schema besteht aus drei Tabellen:
`fuels`, `vehicles`, und `logs`.
---
## Tabelle: `fuels` (Kraftstoffe)
Speichert alle verfügbaren Kraftstofftypen mit ihrer Mengeneinheit.
| Spalte | Typ | Constraint | Beschreibung |
|-------------|-------------|-------------------|---------------------------|
| `id` | INTEGER | PRIMARY KEY | Eindeutige ID |
| `name` | TEXT | NOT NULL UNIQUE | Name des Kraftstoffs |
| `unit` | TEXT | NOT NULL | Mengeneinheit |
### Initiale Daten
| id | name | unit |
|----|--------|-------|
| 0 | Diesel | L |
| 1 | Benzin | L |
| 2 | LPG | L |
| 3 | CNG | L |
| 4 | Strom | kWh |
---
## Tabelle: `vehicles` (Fahrzeuge)
Speichert die Eigenschaften aller Fahrzeuge.
| Spalte | Typ | Constraint | Beschreibung |
|---------------------|-------------|--------------------------|-------------------------------|
| `id` | INTEGER | PRIMARY KEY AUTOINCREMENT| Eindeutige Fahrzeug-ID |
| `name` | TEXT | NOT NULL | Name/Bezeichnung des Fahrzeugs|
| `manufacturer` | TEXT | | Hersteller (optional) |
| `model` | TEXT | | Modell (optional) |
| `year` | INTEGER | | Baujahr (optional) |
| `description` | TEXT | | Beschreibung (optional) |
| `license_plate` | TEXT | | Kennzeichen (optional) |
| `purchase_date` | DATE | | Kaufdatum (optional) |
| `weight_kg` | REAL | | Gewicht in kg (optional) |
| `power_kw` | REAL | | Leistung in kW (optional) |
| `max_odometer` | REAL | | Höchster Kilometerstand (optional) |
| `current_odometer` | REAL | NOT NULL DEFAULT 0 | Aktueller Kilometerstand |
| `fuel_id` | INTEGER | NOT NULL REFERENCES fuels(id) | Fremdschlüssel zu fuels |
| `created_at` | DATETIME | NOT NULL DEFAULT CURRENT_TIMESTAMP | Erstellungszeitpunkt |
| `updated_at` | DATETIME | NOT NULL DEFAULT CURRENT_TIMESTAMP | Letzte Aktualisierung |
### Indizes
- `idx_vehicles_fuel_id` auf `(fuel_id)`
- `idx_vehicles_license_plate` auf `(license_plate)`
- `idx_vehicles_manufacturer` auf `(manufacturer)`
- `idx_vehicles_model` auf `(model)`
---
## Tabelle: `logs` (Logbuch)
Speichert alle Logbucheinträge (Tankungen, Wartung, Reparaturen, Notizen).
| Spalte | Type | Constraint | Beschreibung |
|----------------|-------------|--------------------------|--------------------------------------|
| `id` | INTEGER | PRIMARY KEY AUTOINCREMENT| Eindeutige Log-ID |
| `vehicle_id` | INTEGER | NOT NULL REFERENCES vehicles(id) | Fremdschlüssel zu vehicles |
| `fuel_id` | INTEGER | REFERENCES fuels(id) | Kraftstoff (NULL bei Wartung/Notiz) |
| `log_type` | TEXT | NOT NULL CHECK (log_type IN ('tankung', 'wartung', 'reparatur', 'notiz')) | Eintragsart |
| `odometer` | REAL | NOT NULL | Kilometerstand zum Zeitpunkt des Eintrags |
| `datetime` | DATETIME | NOT NULL DEFAULT CURRENT_TIMESTAMP | Zeitpunkt des Eintrags |
| `cost` | REAL | NOT NULL DEFAULT 0 | Kosten in Euro |
| `quantity` | REAL | NOT NULL DEFAULT 0 | Menge (Kraftstoff in L/kWh) |
| `unit` | TEXT | | Mengeneinheit (kopiert von fuels) |
| `note` | TEXT | | Notiz / Beschreibung (optional, multiline) |
| `created_at` | DATETIME | NOT NULL DEFAULT CURRENT_TIMESTAMP | Erstellungszeitpunkt |
### Indizes
- `idx_logs_vehicle_id` auf `(vehicle_id)`
- `idx_logs_log_type` auf `(log_type)`
- `idx_logs_datetime` auf `(datetime)`
- `idx_logs_vehicle_datetime` auf `(vehicle_id, datetime)`
---
## SQL - Erstellungsstatement
Siehe auch: `internal/db/migration.sql`
```sql
-- fuels
CREATE TABLE fuels (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL UNIQUE,
unit TEXT NOT NULL
);
-- vehicles
CREATE TABLE vehicles (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
manufacturer TEXT,
model TEXT,
year INTEGER,
description TEXT,
license_plate TEXT,
purchase_date DATE,
weight_kg REAL,
power_kw REAL,
max_odometer REAL,
current_odometer REAL NOT NULL DEFAULT 0,
fuel_id INTEGER NOT NULL REFERENCES fuels(id),
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- logs
CREATE TABLE logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
vehicle_id INTEGER NOT NULL REFERENCES vehicles(id),
fuel_id INTEGER REFERENCES fuels(id),
log_type TEXT NOT NULL CHECK (log_type IN ('tankung', 'wartung', 'reparatur', 'notiz')),
odometer REAL NOT NULL,
datetime DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
cost REAL NOT NULL DEFAULT 0,
quantity REAL NOT NULL DEFAULT 0,
unit TEXT,
note TEXT,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- Indizes
CREATE INDEX idx_vehicles_fuel_id ON vehicles(fuel_id);
CREATE INDEX idx_vehicles_license_plate ON vehicles(license_plate);
CREATE INDEX idx_vehicles_manufacturer ON vehicles(manufacturer);
CREATE INDEX idx_vehicles_model ON vehicles(model);
CREATE INDEX idx_logs_vehicle_id ON logs(vehicle_id);
CREATE INDEX idx_logs_log_type ON logs(log_type);
CREATE INDEX idx_logs_datetime ON logs(datetime);
CREATE INDEX idx_logs_vehicle_datetime ON logs(vehicle_id, datetime);
```
---
## Beziehungen
```
fuels 1 ─── N vehicles
vehicles 1 ─── N logs
fuels 0..1 ─── N logs (bei Tankung: fuel_id gesetzt; bei Wartung/Notiz: NULL)
```
---
## Bemerkungen
- `current_odometer` wird automatisch aktualisiert wenn ein Log-Eintrag mit `log_type = 'tankung'` einen höheren Kilometerstand hat.
- Der `unit`-Feld in `logs` wird beim Anlegen eines Eintrags aus der `fuels`-Tabelle kopiert, um historische Konsistenz zu gewährleisten.
- `log_type` ist auf vier Werte beschränkt: `tankung`, `wartung`, `reparatur`, `notiz`.
+61
View File
@@ -0,0 +1,61 @@
# GoCarLog - Projektstruktur
## Verzeichnisstruktur
```
gocarlog/
├── cmd/
│ └── server/
│ └── main.go # Entry point: DB init, Router starten, Server starten
├── internal/
│ ├── db/
│ │ ├── database.go # SQLite-Verbindung, Migrationen, Seed-Daten (Kraftstoffe)
│ │ └── migration.sql # SQL-Statements für Tabellen-Erstellung
│ ├── model/
│ │ ├── fuel.go # Struktur + Methoden für Kraftstoff
│ │ ├── vehicle.go # Struktur + Methoden für Fahrzeug
│ │ └── log.go # Struktur + Methoden für Logbucheintrag
│ ├── handler/
│ │ ├── vehicle.go # HTTP-Handler: POST /api/vehicles, GET /api/vehicles, GET /api/vehicles/:id
│ │ ├── log.go # HTTP-Handler: POST /api/logs, GET /api/logs
│ │ ├── consumption.go # HTTP-Handler: GET /api/vehicles/:id/consumption
│ │ └── static.go # Statische Dateien ausliefern (frontend/)
│ ├── router/
│ │ └── router.go # Router-Setup mit gorilla/mux oder net/http
│ └── middleware/
│ └── middleware.go # CORS, Logging, Error-Handling
├── frontend/
│ ├── index.html # Hauptseite mit SPA-Routing
│ ├── css/
│ │ └── style.css # Dunkles, modernes Design
│ ├── js/
│ │ ├── app.js # SPA-Routing, View-Management
│ │ ├── api.js # API-Client (fetch-Wrapper)
│ │ └── views/
│ │ ├── logs.js # Logbuch-Ansicht
│ │ ├── vehicles.js # Fahrzeugliste
│ │ ├── vehicle-detail.js # Fahrzeugdetails
│ │ └── forms.js # Eingabemasken (Fahrzeug anlegen, Log eintragen)
│ └── assets/
│ └── (Icons, Bilder)
├── docs/
│ ├── project-structure.md # Diese Datei
│ ├── database-schema.md # Datenbank-Struktur (Milestone 3)
│ └── api-spec.md # JSON-Schnittstelle (Milestone 4)
├── tests/ # Integrationstests
│ └── api_test.go
├── go.mod # Go Module Definition
└── README.md
```
## Package-Erklärung
- **`cmd/server`**: Der einzige Entry Point. Initialisiert DB, lädt Router, startet HTTP-Server.
- **`internal/db`**: Datenbankverbindung, Schema-Migrationen, Initialdaten.
- **`internal/model`**: Datenstrukturen (Go structs) und domain-spezifische Methoden.
- **`internal/handler`**: HTTP-Handler-Funktionen (Request → Response).
- **`internal/router`**: URL-Routing-Definitionen.
- **`internal/middleware`**: Cross-cutting concerns (CORS, Logging, Error-Handling).
- **`frontend/`**: Statische Webdateien (HTML/CSS/JS), vom Backend ausgeliefert.
- **`docs/`**: Projektdokumentation.
- **`tests/`**: Testdateien.