# 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*