Initial commit: Beisel Rallye Graz Project with full documentation

2026-06-29 12:20:12 +02:00
commit 7bdc792019
9 changed files with 2193 additions and 0 deletions
@@ -0,0 +1,183 @@
+# Entwicklungshandbuch: Beisel Rallye 🍺
+
+## Schnellstart
+
+### Voraussetzungen
+- Node.js v18+
+- npm oder yarn
+- SQLite3 (wird via npm installiert)
+
+### Setup
+```bash
+# In das Projektverzeichnis wechseln
+cd /home/claw/.openclaw/agents/wisp/workspace/beisel-rally
+
+# Abhängigkeiten installieren
+npm install
+
+# Server starten
+node index.js
+
+# Server läuft auf http://localhost:8083
+```
+
+## Code-Struktur
+
+### Wichtige Dateien
+- `index.js` - Hauptserver mit Express App
+- `views/index.ejs` - Frontend Template  
+- `public/css/style.css` - Styling
+- `beisel_rally.db` - SQLite Datenbank
+- `package.json` - Dependencies und Scripts
+
+### Entwicklungs-Wiederholungszyklus
+1. Code ändern
+2. Server neu starten (`Ctrl+C`, dann `node index.js`)
+3. Im Browser testen (Cache leeren!)
+4. Git commit (wenn fertig)
+
+## Wichtige Konzepte
+
+### Express Middleware
+```javascript
+// Body Parser für JSON Requests
+app.use(express.json());
+
+// Statische Dateien servieren  
+app.use(express.static('public'));
+
+// Custom Middleware (z.B. Logging)
+app.use((req, res, next) => {
+    console.log(`${new Date().toISOString()} - ${req.method} ${req.url}`);
+    next();
+});
+```
+
+### SQLite Operationen
+```javascript
+const sqlite3 = require('sqlite3').verbose();
+const db = new sqlite3.Database('./beisel_rally.db');
+
+// Query ausführen
+db.run("INSERT INTO rally_logs (user_name, district) VALUES (?, ?)", 
+    ["Gregor", "I. Innere Stadt"], function(err) {
+        if (err) {
+            console.error('Insert fehlgeschlagen:', err);
+            return;
+        }
+        console.log('Erfolgreich eingefügt, ID:', this.lastID);
+    });
+
+// Daten abrufen  
+db.all("SELECT * FROM rally_logs WHERE user_name = ?", ["Gregor"], (err, rows) => {
+    if (err) {
+        console.error('Query fehlgeschlagen:', err);
+        return;
+    }
+    console.log(rows);
+});
+```
+
+### Fehlerbehandlung
+```javascript
+// Try-Catch für async Operationen  
+try {
+    const result = await someAsyncOperation();
+    res.json({ success: true, data: result });
+} catch (error) {
+    console.error('Fehler:', error);
+    res.status(500).json({ 
+        success: false, 
+        error: 'Interner Serverfehler' 
+    });
+}
+```
+
+## Testing
+
+### Manuelles Testen
+1. Server starten
+2. Browser öffnen: `http://localhost:8083`
+3. API Endpunkte testen mit curl oder Postman:
+   ```bash
+   # New Visit testen
+   curl -X POST http://localhost:8083/api/visit \
+     -H "Content-Type: application/json" \
+     -d '{"user_name":"Gregor","district":"I. Innere Stadt","beisel_name":"Test"}'
+   
+   # Status abrufen
+   curl http://localhost:8083/api/status/Gregor
+   ```
+
+### Datenbank-Checks
+```bash
+# SQLite CLI starten
+sqlite3 beisel_rally.db
+
+# Alle Einträge anzeigen
+SELECT * FROM rally_logs;
+
+# Statistik pro User
+SELECT user_name, COUNT(*) as visits FROM rally_logs GROUP BY user_name;
+```
+
+## Debugging
+
+### Häufige Probleme
+
+**Server startet nicht:**
+- Port 8083 ist belegt? → `lsof -i :8083` und Prozess killen
+- Node.js Version zu alt? → `node --version` (braucht v18+)
+
+**Datenbank Fehler:**
+- Datei nicht gefunden? → Prüfen ob `beisel_rally.db` existiert
+- Permission denied? → `chmod 664 beisel_rally.db` und Gruppe prüfen
+
+**Frontend lädt nicht:**
+- Cache geleert? → Hard Reload (Ctrl+Shift+R)
+- CORS Fehler? → Server Logs checken
+
+## Best Practices
+
+### Code-Qualität
+- **ESLint** für JavaScript Linting
+- **Prettier** für konsistentes Formatting  
+- **Git Commits** mit klaren Nachrichten
+- **Comments** erklären das "Warum", nicht das "Was"
+
+### Sicherheit
+- **Input Validation** auf allen Endpunkten
+- **Parameterisierte Queries** gegen SQL Injection
+- **Rate Limiting** für API Endpunkte
+- **HTTPS** erzwingen (bereits durch Nginx gegeben)
+
+### Performance  
+- **Datenbank-Verbindungen** schließen wenn nicht benötigt
+- **Caching** für statische Daten (Bezirke, Beiseln)
+- **Pagination** bei großen Datensätzen
+- **Lazy Loading** für komplexe Views
+
+## Deployment Checklist
+
+Vor dem Deployen prüfen:
+- [ ] Alle Tests bestanden
+- [ ] Datenbank-Schema aktuell  
+- [ ] Environment-Variablen gesetzt (falls nötig)
+- [ ] Logging konfiguriert
+- [ ] Backup-Mechanismus vorhanden
+- [ ] Monitoring/Alerting eingerichtet
+
+## Ressourcen
+
+### Offizielle Dokumentation
+- [Express.js](https://expressjs.com/)
+- [SQLite3 Node.js](https://github.com/TryGhost/node-sqlite3)  
+- [Nginx Documentation](https://nginx.org/en/docs/)
+
+### Lokale Hilfe
+- `PROJECT.md` - Projektübersicht
+- `API_DESIGN.md` - API Spezifikation  
+- `ARCHITECTURE.md` - System-Architektur
+
+---
+*Stand: 2026-06-29 | Version: 1.0*