beisel-rally/DEVELOPMENT_GUIDE.md

Entwicklungshandbuch: Beisel Rallye 🍺

Schnellstart

Voraussetzungen

• Node.js v18+
• npm oder yarn
• SQLite3 (wird via npm installiert)

Setup

# 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

// 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

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

// 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:

   # 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

# 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
• SQLite3 Node.js
• Nginx Documentation

Lokale Hilfe

• PROJECT.md - Projektübersicht
• API_DESIGN.md - API Spezifikation
• ARCHITECTURE.md - System-Architektur

---

Stand: 2026-06-29 | Version: 1.0