TicketPilot

Automatische Pipeline von Helpdesk-Tickets (Odoo, AppSignal) über Claude Code CLI zu GitLab Merge Requests.

Überblick

TicketPilot holt automatisch Tickets aus verschiedenen Quellen, bewertet ihre Qualität, bereitet Kontext-Dateien auf und lässt Claude Code CLI Fixes implementieren, die nach einem automatischen Code-Review als Merge Requests in GitLab landen.

Ticket-Quellen

• Odoo — Helpdesk-Tickets werden periodisch per JSON-RPC gepollt
• AppSignal — Error-Incidents können manuell als Tickets importiert werden

Pipeline-Flow

Ticket → Scoring → Klassifikation
                       ├── Autopilot (≥70)  → Prepare → Claude Code → Review → Push → MR
                       ├── Klärfall (30-69)  → Dashboard → Enrichment → Pipeline
                       ├── Abgelehnt (<30)   → Archiv
                       └── Admin-Aufgabe     → Schritt-für-Schritt-Anleitung generieren

Bei einem fehlgeschlagenen Review wird automatisch nachgebessert (max 3 Runden):

Claude Code → Review ──┐
                        ├── APPROVED → Push → MR
                        └── CHANGES_REQUESTED → Claude fixt → Review (max 3 Runden)

Komponenten

1. Polling-Service — Odoo JSON-RPC Client mit konfigurierbaren Stages
2. AppSignal-Integration — GraphQL API für Error-Incidents
3. Scoring-Engine — Regel-basiert (max 40 Punkte) + LLM via Claude CLI (max 60 Punkte)
4. Preparation-Engine — Repo-Zugriff (lokal oder Clone), kontext.md + ticket_context.md Generator
5. Claude Code Runner — Führt Claude Code CLI als Subprocess aus
6. Review Agent — Automatisches Code-Review mit Feedback-Loop
7. GitLab Service — MR-Erstellung mit Push
8. Web-Dashboard — React-Frontend mit WebSocket Live-Updates

Slash Commands (Entwickler-Workflow)

Neben der automatischen Pipeline gibt es Slash Commands für die manuelle Arbeit mit Issues:

/issue → /fix → /merge → /check-merge → /review → /doku

Command	Was passiert	Label-Wechsel
/issue <Beschreibung>	Issue erstellen mit Code-Analyse, Refinement und Labels	—
/issues	Alle offenen Issues als Tabelle anzeigen	—
/fix <NR>	Branch erstellen, implementieren, committen, PR erstellen	—
/merge	PR für aktuellen Branch erstellen	→ review
/check-merge <NR>	Code-Review mit Tests, dann merge oder Feedback	—
/review <NR>	Funktionstest nach Merge	review → doku
/doku <NR>	Docs + Memory aktualisieren, Issue schließen	doku → closed
/close <NR>	Issue manuell schließen (Shortcut)	—

Labels (werden automatisch bei /issue vergeben):

Kategorie	Labels
Art	bug, feature, improvement
Bereich	backend, frontend, database, service, api
Komplexität	S, M, L, XL
Wichtigkeit	kritisch, wichtig, normal, niedrig
Workflow	review, doku

Setup

Voraussetzungen

• Python 3.12+
• Node.js 20+
• Claude Code CLI (claude) — muss installiert sein, kein API-Key nötig
• Git

Installation

# Backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Frontend
cd frontend
npm install
cd ..

Konfiguration

cp .env.example .env

.env bearbeiten:

Variable	Beschreibung
ODOO_URL	URL der Odoo-Instanz
ODOO_DB	Odoo-Datenbankname
ODOO_USER	Odoo Login (z.B. admin)
ODOO_PASSWORD	Odoo Passwort oder API-Key
ODOO_ASSIGNED_USER_ID	User-ID dessen Tickets geholt werden
ODOO_STAGE_NAMES	Kommagetrennte Stage-Namen (auch über UI konfigurierbar)
GITLAB_URL	GitLab-URL (z.B. https://git.example.com)
GITLAB_TOKEN	GitLab Personal Access Token
GITLAB_ASSIGNEE_ID	Deine GitLab User-ID für MR-Assignee
APPSIGNAL_API_TOKEN	AppSignal Personal API Token (optional)
APPSIGNAL_ORG_SLUG	AppSignal Organization Slug (optional)
CLAUDE_CODE_PATH	Absoluter Pfad zur Claude CLI
PROJECTS_BASE_DIR	Verzeichnis wo lokale Repos liegen (z.B. /Users/me/Projects)

Datenbank

TicketPilot nutzt SQLite mit Alembic-Migrationen. Die DB wird beim Start automatisch migriert.

# Manuell migrieren
alembic upgrade head

# Neue Migration erstellen (nach Model-Änderungen)
alembic revision --autogenerate -m "beschreibung"

Starten

# Backend (Terminal 1)
source .venv/bin/activate
uvicorn backend.main:app --reload --port 8000

# Frontend (Terminal 2)
cd frontend
npm run dev

Dashboard: http://localhost:3000

Tests

source .venv/bin/activate
pytest tests/ -v

Features

Ticket-Verarbeitung

• Odoo-Polling: Automatisches Abholen von Tickets inkl. Tags, Bilder, HTML→Plaintext
• AppSignal-Import: Error-Incidents manuell als Tickets importieren
• Scoring: Bewertet ob ein Ticket automatisch lösbar ist (Regel + LLM)
• Ticket-Typen: Erkennt automatisch ob Code-Änderung oder Admin-Aufgabe
  • Code: Vollständige Pipeline bis zum MR
  • Admin: Generiert Schritt-für-Schritt-Anleitung mit konkreten Shell-Commands

Repo-Management

• Repo-Registry: Repos über UI oder GitLab-Import anlegen
• GitLab-Import: Alle Projekte aus GitLab laden, lokale Clones automatisch erkennen
• Lokale Repos: Arbeitet direkt mit lokalen Verzeichnissen (kein Clone nötig)
• Repo-Analyse: Claude analysiert Repos und erstellt PROJEKTKONTEXT.md
• Cross-Repo-Zugriff: Claude kann andere Repos lesen für Kontext

Pipeline

• Persistent Context: ticket_context.md akkumuliert alles Wissen über alle Schritte
• Code-Review: Automatisches Review nach Claude Code Run
• Review-Fix-Loop: Bei CHANGES_REQUESTED bessert Claude automatisch nach (max 3 Runden)
• Odoo-Rückfrage: Generiert nutzerfreundliche Rückfragen ans Odoo-Ticket

Stabilität

• Watchdog: Resettet hängende Tickets nach 15 Minuten
• Error-Recovery: Beim Server-Neustart werden laufende Tickets zurückgesetzt
• Alembic-Migrationen: Schema-Änderungen ohne Datenverlust
• WebSocket mit Reconnect: Automatische Wiederverbindung bei Abbruch

Dashboard

• Ticket-Übersicht: Filter nach Status, Klassifikation, Quelle
• Ticket-Detail: Scoring, Review, Kontext, kontext.md, Pipeline-Log
• Auto-Refresh: Aktive Tickets werden alle 3 Sekunden aktualisiert
• Bilder: Screenshots aus Tickets werden angezeigt
• Enrichment: Repo zuweisen, Notizen ergänzen, Pipeline starten
• Rückfrage: Freundliche Nachricht an Ticket-Ersteller senden
• Repo-Registry: Repos verwalten, GitLab importieren, analysieren
• Settings: Polling-Intervall, Stages, Schwellwerte, Projekte-Verzeichnis

Projektstruktur

ticketpilot/
├── backend/
│   ├── main.py                    # FastAPI App, Scheduler, WebSocket
│   ├── config.py                  # Settings aus .env
│   ├── database.py                # SQLAlchemy + SQLite
│   ├── models/
│   │   ├── ticket.py              # Ticket ORM Model
│   │   └── repo.py                # Repo-Registry ORM Model
│   ├── services/
│   │   ├── odoo_poller.py         # Odoo JSON-RPC Polling + Bilder
│   │   ├── appsignal_service.py   # AppSignal GraphQL Client
│   │   ├── scoring_engine.py      # Regel + LLM Scoring via Claude CLI
│   │   ├── preparation_engine.py  # kontext.md Generator
│   │   ├── claude_runner.py       # Claude Code CLI Wrapper
│   │   ├── review_agent.py        # Automatisches Code-Review
│   │   ├── gitlab_service.py      # GitLab MR Client
│   │   ├── repo_analyzer.py       # Git-Operationen, Repo-Registry
│   │   ├── repo_context_builder.py # PROJEKTKONTEXT.md Generator
│   │   ├── context_file.py        # ticket_context.md Management
│   │   └── pipeline.py            # Pipeline-Orchestrierung
│   ├── api/
│   │   ├── tickets.py             # Ticket REST Endpoints
│   │   ├── repos.py               # Repo-Registry + GitLab-Import
│   │   ├── appsignal.py           # AppSignal Endpoints
│   │   └── pipeline.py            # Stats + Settings Endpoints
│   ├── prompts/
│   │   ├── scoring_prompt.py      # LLM Scoring Prompt
│   │   └── admin_prompt.py        # Admin-Aufgaben Prompt
│   └── templates/
│       └── kontext_template.md    # Jinja2 Template
├── frontend/
│   └── src/
│       ├── App.tsx                # Router + Layout
│       ├── pages/
│       │   ├── Dashboard.tsx      # Ticket-Übersicht
│       │   ├── TicketDetail.tsx   # Detail + Enrichment + Review
│       │   ├── RepoRegistry.tsx   # Repo-Verwaltung + GitLab-Import
│       │   ├── AppSignal.tsx      # AppSignal Error-Incidents
│       │   └── Settings.tsx       # Konfiguration
│       ├── components/
│       │   ├── StatsBar.tsx
│       │   ├── TicketList.tsx
│       │   ├── TicketCard.tsx
│       │   ├── ScoreDisplay.tsx
│       │   ├── EnrichmentForm.tsx
│       │   └── PipelineStatus.tsx
│       └── api/
│           └── client.ts          # Typisierter API Client
├── alembic/                       # DB-Migrationen
│   ├── env.py
│   └── versions/
├── alembic.ini
├── repo_registry.yaml             # Fallback Repo-Konfiguration
├── requirements.txt
├── docker-compose.yml
└── .env.example

API Endpoints

Tickets

Methode	Pfad	Beschreibung
GET	/api/tickets	Ticket-Liste (Filter: status, classification, source)
GET	/api/tickets/{id}	Ticket-Details
PATCH	/api/tickets/{id}/enrich	Ticket anreichern
POST	/api/tickets/{id}/start	Pipeline manuell starten
POST	/api/tickets/{id}/retry	Ticket erneut verarbeiten
POST	/api/tickets/{id}/reject	Ticket ablehnen
POST	/api/tickets/{id}/reset	Ticket zurücksetzen
POST	/api/tickets/{id}/create-mr	MR nachträglich erstellen
POST	/api/tickets/{id}/ask-back	Rückfrage an Odoo senden
GET	/api/tickets/{id}/kontext	Generierte kontext.md
GET	/api/tickets/{id}/log	Pipeline-Log
GET	/api/tickets/{id}/images/{idx}	Ticket-Bild

Repos

Methode	Pfad	Beschreibung
GET	/api/repos	Alle Repos
POST	/api/repos	Neues Repo anlegen
PUT	/api/repos/{name}	Repo aktualisieren
GET	/api/repos/gitlab-projects	Projekte aus GitLab laden
POST	/api/repos/{name}/analyze	Repo-Analyse starten
POST	/api/repos/{name}/write-context	PROJEKTKONTEXT.md schreiben

AppSignal

Methode	Pfad	Beschreibung
GET	/api/appsignal/apps	Apps aus AppSignal laden
GET	/api/appsignal/apps/{id}/incidents	Error-Incidents einer App
POST	/api/appsignal/import	Incident als Ticket importieren

System

Methode	Pfad	Beschreibung
GET	/api/health	Health Check
GET	/api/stats	Dashboard-Statistiken
GET	/api/pipeline/status	Laufende/wartende Jobs
GET	/api/settings	Aktuelle Einstellungen
POST	/api/settings	Einstellungen ändern
WS	/ws/updates	Live-Updates

Scoring

Regel-Check (max 40 Punkte)

• Beschreibung > 50 Zeichen: 0-15 Punkte
• Repo/Modul-Tag vorhanden: 0-15 Punkte
• Fehlermeldung/Stacktrace: 0-10 Punkte
• Steps-to-Reproduce: 0-10 Punkte

LLM-Bewertung (max 60 Punkte)

• Klarheit Was (Gewicht 42%) — Was soll geändert werden?
• Klarheit Wo (Gewicht 33%) — Welcher Bereich ist betroffen?
• Kontext (Gewicht 25%) — Reicht der fachliche Kontext?

Das LLM bewertet dabei nur den fachlichen Kontext — technische Details wie Dateinamen oder Funktionen werden nicht negativ bewertet, da der Agent diese selbst im Code finden kann.

Klassifikation

• Autopilot (≥70): Automatische Bearbeitung
• Klärfall (30-69): Manuelle Überprüfung/Anreicherung nötig
• Abgelehnt (<30): Nicht automatisierbar

Ticket-Typ-Erkennung

• Code: Bug-Fix, Feature, Refactoring → vollständige Pipeline
• Admin: Konfiguration, Deployment, Berechtigungen → Schritt-für-Schritt-Anleitung

Kontext-System

TicketPilot nutzt mehrere Kontext-Dateien um sicherzustellen, dass kein Wissen verloren geht:

• PROJEKTKONTEXT.md — Pro Repo, beschreibt Architektur, Tech-Stack, Struktur. Wird bei Repo-Analyse erstellt und liegt im Repo-Verzeichnis.
• kontext.md — Pro Ticket, enthält Ticket-Info, Scoring, relevante Dateien. Wird vor dem Claude Code Run erstellt.
• ticket_context.md — Akkumuliert den gesamten Verlauf eines Tickets (Ticket, Kontext, Claude-Ausgabe, Review-Feedback, Fix-Runden). Wird in der DB gespeichert und ist über das Dashboard einsehbar.