Add comprehensive README.md

This commit is contained in:
2026-06-07 13:52:41 +02:00
parent 1d17422093
commit 042ef02fbb
+154
View File
@@ -0,0 +1,154 @@
# 🚗 GoCarLog
**Fahrzeug-Verwaltung & Logbuch** — Ein modernes Web-Application für die Verwaltung von Fahrzeugen und deren Wartungshistorie, geschrieben in Go mit SQLite.
[![Go](https://img.shields.io/badge/Go-1.19+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![SQLite](https://img.shields.io/badge/SQLite-3-003B57?style=flat&logo=sqlite)](https://www.sqlite.org/)
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
## ✨ Features
- **Fahrzeugverwaltung** – Anlegen, Bearbeiten und Verwalten mehrerer Fahrzeuge
- **Logbuch** – Einträge für Tankungen, Wartungen, Reparaturen und Notizen
- **Verbrauchsberechnung** – Automatischer Durchschnittsverbrauch und Verbrauch pro Tankung (L/100km)
- **Automatische Odometer-Aktualisierung** – Kilometerstand wird bei Tankungen aktualisiert
- **Filter & Sortierung** – Logbucheinträge und Fahrzeuge nach verschiedenen Kriterien filtern und sortieren
- **Kostenübersicht** – Gesamtkosten pro Log-Typ (Tankung, Wartung, Reparatur, Notiz)
- **Modernes UI** – Dark Theme, responsive Design, clientseitige Sortierung
## 🏗 Technologie-Stack
| Schicht | Technologie |
|---------|------------|
| **Backend** | Go (Golang) 1.19+ |
| **Datenbank** | SQLite (via `github.com/mattn/go-sqlite3`) |
| **Frontend** | HTML5, CSS3, Vanilla JavaScript |
| **Deployment** | Statische Single-Binary, eingebettetes Frontend |
## 📁 Projektstruktur
```
gocarlog/
├── cmd/server/main.go # Anwendungseinstiegspunkt
├── internal/ # Interne Pakete
│ ├── db/ # Datenbank-Schicht (Migration, Seed)
│ ├── model/ # Datenmodelle und Business-Logik
│ ├── handler/ # HTTP-Handler für API-Endpunkte
│ ├── middleware/ # HTTP-Middleware (CORS, Logging)
│ └── router/ # Router-Konfiguration
├── frontend/ # Statische Web-Assets
│ ├── index.html # Hauptseite
│ ├── css/style.css # Stylesheet (Dark Theme)
│ ├── js/app.js # Frontend-Logik
│ └── assets/ # Icons, Bilder
├── tests/ # Backend-Unit-Tests
│ ├── model_test.go
│ ├── handler_test.go
│ └── database_test.go
├── docs/ # Dokumentation
│ ├── database-schema.md # Datenbank-Schema
│ ├── api-spec.md # API-Spezifikation
│ └── project-structure.md # Projektstruktur
├── DEVELOPMENT.md # Entwicklungsstatus
├── go.mod / go.sum # Go-Module-Abhängigkeiten
└── gocarlog # Kompiliertes Binary
```
## 🗄 Datenbank-Struktur
Drei Tabellen mit Fremdschlüssel-Beziehungen:
| Tabelle | Beschreibung |
|---------|-------------|
| `fuels` | Kraftstofftypen (Diesel, Benzin, LPG, CNG, Strom) mit Mengeneinheit |
| `vehicles` | Fahrzeugeigenschaften (Name, Hersteller, Modell, Kennzeichen, Odometer, etc.) |
| `logs` | Logbucheinträge (Tankung, Wartung, Reparatur, Notiz) |
**Auto-Update:** Der `current_odometer` eines Fahrzeugs wird automatisch aktualisiert, wenn ein Tankungs-Eintrag mit einem höheren Kilometerstand erstellt wird.
→ Siehe [`docs/database-schema.md`](docs/database-schema.md) für das vollständige Schema.
## 🔌 API
Alle Endpunkte unter `/api/v1/...`, Antwortformat: JSON.
| Methode | Pfad | Beschreibung |
|---------|------|-------------|
| `GET` | `/api/v1/fuels` | Alle Kraftstoffe |
| `POST` | `/api/v1/vehicles` | Neues Fahrzeug erstellen |
| `GET` | `/api/v1/vehicles` | Fahrzeuge auflisten (Filter: Name, Kennzeichen, Kraftstoff, etc.) |
| `GET` | `/api/v1/vehicles/:id` | Fahrzeugdetails |
| `POST` | `/api/v1/logs` | Logbucheintrag erstellen |
| `GET` | `/api/v1/logs` | Logbucheinträge (Filter: Fahrzeug, Typ, Zeitraum) |
| `GET` | `/api/v1/vehicles/:id/consumption` | Durchschnittsverbrauch berechnen |
→ Siehe [`docs/api-spec.md`](docs/api-spec.md) für vollständige Spezifikation mit Request-/Response-Beispielen.
## 🚀 Installation
### Voraussetzungen
- **Go** 1.19 oder neuer
- **GCC** (für CGO/SQLite-Unterstützung)
### Kompilieren
```bash
git clone https://git.jlserver.de/JLtec/gocarlog.git
cd gocarlog
go build -o gocarlog ./cmd/server
```
### Ausführen
```bash
# Server starten (Standard-Port: 8080)
./gocarlog
# Eigenen Port setzen
PORT=3000 ./gocarlog
```
Der Server liefert sowohl die API als auch das Frontend aus:
| URL | Funktion |
|-----|----------|
| `http://localhost:8080/` | Frontend |
| `http://localhost:8080/api/v1/...` | REST API |
| `http://localhost:8080/static/...` | Statische Assets |
## 🧪 Tests
```bash
# Alle Tests
go test ./tests/...
# Mit Deckungsbericht
go test -cover ./tests/...
```
## 🖥 Frontend-Ansichten
- **Logbuch** – Tabellarische Übersicht mit Filtern, Sortierung und Verbrauchsspalte
- **Fahrzeuge** – Fahrzeugliste mit Filterung
- **Fahrzeugdetails** – Vollständige Fahrzeugdaten + Durchschnittsverbrauch
## 📝 Log-Typen
| Typ | Beschreibung |
|-----|-------------|
| `tankung` | Kraftstofftankung (mit Menge, Kosten, Verbrauchsberechnung) |
| `wartung` | Wartungsarbeiten |
| `reparatur` | Reparaturen |
| `notiz` | Freie Notiz |
## 🔮 Geplante Erweiterungen
- [ ] Export-Funktion (CSV/JSON)
- [ ] Diagramme / Graphen (Verbrauch über Zeit)
- [ ] Benutzer-Accounts & Authentifizierung
- [ ] Verbrauch-Filter in Logbuch-Ansicht
## 📄 Lizenz
MIT License