184 lines
4.5 KiB
Markdown
184 lines
4.5 KiB
Markdown
# 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*
|