From 042ef02fbbbc3f8bb0fbeeef094f71da67e7e09f Mon Sep 17 00:00:00 2001 From: Hermes Bot Date: Sun, 7 Jun 2026 13:52:41 +0200 Subject: [PATCH] Add comprehensive README.md --- README.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0598c4c --- /dev/null +++ b/README.md @@ -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