Carambus Entwicklerleitfaden¶

Inhaltsverzeichnis¶

Übersicht
Architektur
Erste Schritte
Datenbank-Setup
Datenbankdesign
Kern-Models
Hauptfunktionen
Entwicklungsworkflow
Deployment
Mitwirken

Übersicht {#uebersicht}¶

Carambus ist ein umfassendes Billard-Turnierverwaltungssystem, das mit Ruby on Rails entwickelt wurde. Es bietet eine vollständige Automatisierung der Billard-Betriebsabläufe von der Turnierplanung bis zur Datenerfassung und Ergebnisübertragung.

Hauptfunktionen¶

Turnierverwaltung: Vollständige Turnierlebenszyklus-Verwaltung
Echtzeit-Scoreboards: Live-Scoreboard-Anzeigen mit WebSocket-Unterstützung
Ligaverwaltung: Team-basierte Ligaorganisation
Datensynchronisation: Integration mit externen Billard-Datenbanken (BA/CC)
Mehrsprachige Unterstützung: Deutsche und englische Benutzeroberflächen
Responsive Design: Funktioniert auf Desktop- und Mobilgeräten

Technologie-Stack¶

Backend: Ruby on Rails 7.2
Datenbank: PostgreSQL
Frontend: Hotwire (Turbo + Stimulus) + Stimulus Reflex
Echtzeit: Action Cable mit Redis
Authentifizierung: Devise
Autorisierung: Pundit + CanCanCan
Admin-Interface: Administrate
Deployment: Capistrano + Puma

Architektur¶

Rails-Struktur¶

Carambus folgt den Standard-Rails-Konventionen mit einigen Anpassungen:

app/
├── controllers/          # RESTful Controller
├── models/              # ActiveRecord Models mit Concerns
├── views/               # ERB Templates
├── javascript/          # Stimulus Controller und Utilities
├── channels/            # Action Cable Channels
├── jobs/                # Hintergrund-Jobs
├── services/            # Geschäftslogik-Services
└── helpers/             # View Helper

Wichtige Architekturmuster¶

Concerns¶

Die Anwendung verwendet Rails Concerns, um Funktionalität zu teilen:

LocalProtector: Schützt lokale Daten vor externen Änderungen
SourceHandler: Verwaltet externe Datensynchronisation
RegionTaggable: Behandelt regionsbasierte Datenorganisation

Echtzeit-Funktionen¶

Action Cable: WebSocket-Verbindungen für Live-Updates
Stimulus Reflex: Server-seitige Reflexe für reaktive UI
Cable Ready: Client-seitige DOM-Manipulation

Erste Schritte¶

Voraussetzungen¶

Ruby 3.2+ (siehe .ruby-version)
PostgreSQL 11+
Redis 5+
Node.js 14+ (für Asset-Kompilierung)

Installation¶

Repository klonen
```
git clone <repository-url>
cd carambus
```
Abhängigkeiten installieren
```
bundle install
yarn install
```

Datenbank einrichten

cp config/database.yml.example config/database.yml
# database.yml mit Ihren PostgreSQL-Zugangsdaten bearbeiten

# Option 1: Bestehenden Datenbank-Dump importieren (empfohlen)
# Stellen Sie sicher, dass Sie eine Datenbank-Dump-Datei haben (z.B., carambus_api_development_YYYYMMDD_HHMMSS.sql)
# Datenbank erstellen und Dump importieren:
createdb carambus_development
psql -d carambus_development -f /pfad/zu/ihrem/dump.sql

# Option 2: Neue Datenbank erstellen (falls kein Dump verfügbar)
rails db:create
rails db:migrate
rails db:seed

Umgebungskonfiguration

cp config/application.yml.example config/application.yml
# application.yml mit Ihrer Konfiguration bearbeiten

Anwendung starten
```
rails server
```

Entwicklungstools¶

Code-Qualität¶

RuboCop: Code-Stil-Erzwingung
Standard: Ruby-Code-Formatierung
Brakeman: Sicherheitslücken-Scanning
Overcommit: Git-Hooks für Code-Qualität

Testing¶

RSpec: Unit- und Integrationstests
Capybara: Systemtests
Factory Bot: Test-Daten-Factories

Datenbank-Setup {#datenbank-setup}¶

Für die Einrichtung einer neuen Entwicklungsdatenbank wird empfohlen, einen bestehenden Datenbank-Dump zu importieren. Detaillierte Anweisungen finden Sie in der separaten Dokumentation:

🗄️ Datenbank-Setup Anleitung

Schnellstart¶

# Datenbank erstellen
createdb carambus_development

# Dump importieren
psql -d carambus_development -f /pfad/zu/ihrem/dump.sql

Erwartete Fehler¶

Beim Import können folgende Fehler auftreten, die ignoriert werden können: - relation "table_name" already exists - Tabelle existiert bereits - multiple primary keys for table "table_name" are not allowed - Primärschlüssel bereits definiert - relation "index_name" already exists - Index existiert bereits - constraint "constraint_name" for relation "table_name" already exists - Constraint bereits definiert

Diese Fehler sind normal, wenn die Datenbank bereits teilweise initialisiert wurde.

Datenbankdesign¶

Kern-Models¶

Seeding Model (Doppelzweck)¶

Das Seeding Model dient zwei verschiedenen Zwecken:

Team-Kader-Verwaltung
Verbunden mit LeagueTeam über league_team_id
Verwaltet den vollständigen Spielerkader für ein Ligateam
Wird während der initialen Liga/Team-Einrichtung erstellt
Spiel-Teilnahme-Verfolgung
Verbunden mit Party über polymorphic tournament_id
Verfolgt, welche Spieler an bestimmten Spielen teilnehmen
Wird beim Einrichten einzelner Spiele erstellt

class Seeding < ApplicationRecord
  belongs_to :player, optional: true
  belongs_to :tournament, polymorphic: true, optional: true
  belongs_to :league_team, optional: true
  include LocalProtector
  include SourceHandler
  include RegionTaggable
end

Party und LeagueTeam Beziehung¶

class Party < ApplicationRecord
  belongs_to :league_team_a, class_name: "LeagueTeam"
  belongs_to :league_team_b, class_name: "LeagueTeam"
  belongs_to :host_league_team, class_name: "LeagueTeam"
  has_many :seedings, as: :tournament
  include LocalProtector
  include SourceHandler
end

Datenspeicherungsmuster¶

Flexible Datenspeicherung¶

Mehrere Models verwenden serialisierte Spalten für flexible Datenspeicherung:

# JSON Serialisierung
serialize :data, coder: JSON, type: Hash
# Verwendet in: Party, Seeding, LeagueTeam

# YAML Serialisierung  
serialize :remarks, coder: YAML, type: Hash
# Verwendet in: Party

Regions-Tagging-System¶

Das RegionTaggable Concern bietet intelligente Regions-Behandlung:

# Automatisches Regions-Tagging basierend auf Kontext
when Seeding
  if tournament_id.present?
    # Turnier-basiertes Regions-Tagging
    tournament ? [
      tournament.region_id,
      (tournament.organizer_type == "Region" ? tournament.organizer_id : nil),
      find_dbu_region_id_if_global
    ].compact : []
  elsif league_team_id.present?
    # Liga-Team-basiertes Regions-Tagging
    league_team&.league ? [
      (league_team.league.organizer_type == "Region" ? league_team.league.organizer_id : nil),
      find_dbu_region_id_if_global
    ].compact : []
  end

Kern-Models¶

Turnierverwaltung¶

Tournament: Haupt-Turnier-Entität
Discipline: Spieltypen (z.B. 3-Banden, 1-Bande)
Player: Einzelne Spieler
Seeding: Turnier-Teilnahme und Ranglisten

Ligaverwaltung¶

League: Liga-Organisation
LeagueTeam: Teams innerhalb von Ligen
Party: Einzelne Spiele zwischen Teams
Season: Liga-Saisons

Standortverwaltung¶

Location: Billard-Clubs/Standorte
Table: Einzelne Billard-Tische
TableMonitor: Echtzeit-Tischüberwachung
TableLocal: Lokale Tisch-Konfigurationen

Benutzerverwaltung¶

User: Systembenutzer mit Devise-Authentifizierung
Role: Benutzerrollen und Berechtigungen
Admin: Administratives Interface über Administrate

Hauptfunktionen¶

Echtzeit-Scoreboards¶

Das Scoreboard-System bietet Live-Updates für Turnier-Anzeigen:

Komponenten¶

Tisch-Monitor: Echtzeit-Spielverfolgung
Scoreboard-Anzeige: Öffentliche Scoreboard-Ansichten
WebSocket-Integration: Live-Updates über Action Cable

Einrichtung¶

Siehe Docker-Installation für detaillierte Konfiguration.

Datensynchronisation¶

Integration mit externen Billard-Datenbanken:

Externe Quellen¶

BA (Billard-Verband): Offizielle Spieler- und Turnierdaten
CC (Competition Center): Wettkampf-Management-System

Synchronisationsprozess¶

Externe Daten werden über API abgerufen
Lokale Daten sind vor externen Änderungen geschützt
Regions-Tagging wird automatisch angewendet
Konflikte werden basierend auf Quellen-Priorität gelöst

Turnier-Workflows¶

Turnier-Erstellung¶

Turnier mit Disziplin und Einstellungen erstellen
Teilnehmer definieren (Spieler/Teams)
Spielpläne generieren
Turnier mit Echtzeit-Überwachung starten

Spiel-Management¶

Spiele planen (Parties)
Live-Spielfortschritt verfolgen
Ergebnisse und Ranglisten aufzeichnen
Berichte und Statistiken generieren

Entwicklungsworkflow¶

Code-Stil¶

Das Projekt verwendet Standard Ruby für Code-Formatierung:

# Code formatieren
bundle exec standardrb --fix

# Auf Probleme prüfen
bundle exec standardrb

Git-Workflow¶

Feature-Branch von main erstellen
Änderungen mit Tests vornehmen
Code-Qualitätsprüfungen ausführen
Pull Request einreichen

Testing¶

# Alle Tests ausführen
rails test

# Bestimmte Test-Datei ausführen
rails test test/models/tournament_test.rb

# Systemtests ausführen
rails test:system

Datenbank-Migrationen¶

# Migration generieren
rails generate migration AddFieldToModel

# Migrationen ausführen
rails db:migrate

# Zurückrollen
rails db:rollback

Deployment¶

Produktions-Setup¶

Die Anwendung ist für den Einsatz auf Raspberry Pi oder ähnlicher Hardware konzipiert:

Systemanforderungen¶

Hardware: Raspberry Pi 4 (4GB RAM empfohlen)
OS: Raspberry Pi OS (32-bit)
Datenbank: PostgreSQL 11+
Web-Server: Nginx + Puma

Deployment-Prozess¶

Server-Setup: Siehe Runbook für detaillierte Server-Konfiguration
Anwendungs-Deployment: Capistrano-basiertes Deployment
Service-Management: Systemd-Services für Autostart
Scoreboard-Setup: Automatisierter Scoreboard-Start

Konfigurationsdateien¶

Datenbank-Konfiguration¶

# config/database.yml
production:
  adapter: postgresql
  database: carambus_production
  host: localhost
  username: www_data
  password: <%= ENV['DATABASE_PASSWORD'] %>

Anwendungs-Konfiguration¶

# config/application.yml
defaults: &defaults
  database_url: postgresql://www_data:password@localhost/carambus_production
  redis_url: redis://localhost:6379/0
  secret_key_base: <%= ENV['SECRET_KEY_BASE'] %>

Service-Management¶

# Anwendung starten
sudo systemctl start carambus

# Autostart aktivieren
sudo systemctl enable carambus

# Status prüfen
sudo systemctl status carambus

Mitwirken¶

Entwicklungsumgebung¶

Folgen Sie dem Erste Schritte Leitfaden
Pre-commit-Hooks einrichten: bundle exec overcommit --install
Machen Sie sich mit dem Datenbankdesign vertraut

Code-Beiträge¶

Repository forken
Feature-Branch erstellen
Änderungen vornehmen
Tests für neue Funktionalität hinzufügen
Sicherstellen, dass alle Tests bestehen
Pull Request einreichen

Dokumentation¶

Relevante Dokumentation bei Hinzufügen von Features aktualisieren
Code-Beispiele für neue APIs einschließen
Konfigurationsänderungen dokumentieren

Test-Richtlinien¶

Tests für alle neue Funktionalität schreiben
Test-Abdeckung über 80% halten
Integrationstests für komplexe Workflows einschließen
Sowohl deutsche als auch englische Locales testen

Code-Review-Prozess¶

Alle Änderungen erfordern Code-Review
Automatisierte Prüfungen müssen bestehen
Manuelles Testing auf Staging-Umgebung
Dokumentations-Updates nach Bedarf

Zusätzliche Ressourcen¶

Dokumentation¶

Datenbankdesign: Detailliertes Datenbankschema
Docker-Installation: Docker-Installation
Turnierverwaltung: Turnier-Workflows
Installationsübersicht: Installationsübersicht

Externe Links¶

Support¶

Issues: Verwenden Sie GitHub Issues für Bug-Reports und Feature-Requests
Diskussionen: GitHub Discussions für Fragen und Ideen
Dokumentation: Dokumentation mit Änderungen aktuell halten

Diese Dokumentation wird vom Carambus-Entwicklungsteam gepflegt. Für Fragen oder Beiträge siehe den Mitwirken Abschnitt.