# Mögliche Erweiterung: Gitea-Integration

## Status

Konzeptvorschlag – noch nicht implementiert.

## Ziel

my2dos soll Issues in einer Gitea-Instanz erstellen können. Die Erfassung erfolgt direkt über einen Slash-Befehl. In einer ersten Version findet keine automatische bidirektionale Synchronisation statt.

## Vorgeschlagene Bedienung

### Issue im Standard-Repository erstellen

```text
/issue Fehler beim Speichern
Weitere Beschreibung des Problems.
```

### Repository über einen Alias auswählen

```text
/issue my2dos Fehler beim Speichern
Weitere Beschreibung des Problems.
```

Dabei könnte `my2dos` beispielsweise auf `rucki/my2dos` verweisen.

### Mögliche spätere Optionen

```text
/issue my2dos Fehler beim Speichern /labels bug,frontend
```

Weitere denkbare Angaben:

- Labels
- zuständige Person
- Meilenstein
- Priorität
- Gitea-Projekt

Die genaue Syntax sollte erst nach Erfahrungen mit der Basisversion festgelegt werden.

## Verhalten der ersten Version

1. Benutzer gibt `/issue` mit Titel und optionaler Beschreibung ein.
2. my2dos bestimmt das Standard-Repository oder löst den angegebenen Alias auf.
3. Das Issue wird über die Gitea-REST-API erstellt.
4. In my2dos wird ein lokaler Link-Eintrag zum Issue angelegt.
5. Issue-Nummer, Repository und URL werden lokal gespeichert.
6. Schlägt der API-Aufruf fehl, bleibt der eingegebene Text als lokaler Eintrag erhalten und zeigt einen verständlichen Fehlerstatus.

Der Text darf bei Netzwerk- oder Gitea-Fehlern nicht verloren gehen.

## Einstellungen

In den Benutzereinstellungen könnte ein Bereich **Gitea** ergänzt werden:

- URL der Gitea-Instanz
- API-Token
- Standard-Repository
- optionale Repository-Aliase
- Verbindung testen

Beispiel für Aliase:

| Alias | Gitea-Repository |
|---|---|
| `my2dos` | `rucki/my2dos` |
| `website` | `rucki/website` |

Später könnten Verbindungen auch einem Team statt nur einem Benutzer gehören.

## Mögliches Datenmodell

### `GiteaConnection`

- Benutzer oder Team
- Server-URL
- verschlüsselter API-Token
- aktiv/inaktiv
- Erstellungs- und Änderungszeitpunkt

### `GiteaRepository`

- Gitea-Verbindung
- Alias
- Owner
- Repository-Name
- Kennzeichnung als Standard-Repository

### `ExternalIssue`

- lokaler my2dos-Eintrag
- Gitea-Repository
- Issue-Nummer
- externe URL
- Synchronisationsstatus
- letzte Fehlermeldung
- Zeitpunkt der letzten Synchronisation

Alternativ könnte `ExternalIssue` später zu einem allgemeinen Modell für externe Systeme erweitert werden.

## Gitea-API

Zum Erstellen eines Issues wird voraussichtlich folgender Endpunkt verwendet:

```http
POST /api/v1/repos/{owner}/{repository}/issues
Authorization: token <API-TOKEN>
Content-Type: application/json
```

Beispielinhalt:

```json
{
  "title": "Fehler beim Speichern",
  "body": "Weitere Beschreibung des Problems."
}
```

Die genaue API muss gegen die eingesetzte Gitea-Version geprüft werden.

## Fehlerbehandlung

Zu berücksichtigen sind insbesondere:

- Gitea nicht erreichbar
- Zeitüberschreitung
- ungültiger oder abgelaufener Token
- fehlende Berechtigung für das Repository
- unbekannter Repository-Alias
- Repository nicht gefunden
- ungültige Labels oder Meilensteine

Ein externer API-Aufruf sollte ein kurzes Timeout besitzen. Fehler müssen im lokalen Eintrag nachvollziehbar sein. Für spätere automatische Wiederholungen wäre ein Hintergrundjob sinnvoll.

## Sicherheit

- API-Tokens dürfen nicht im Klartext angezeigt oder protokolliert werden.
- Tokens sollten verschlüsselt gespeichert oder zunächst über Umgebungsvariablen bereitgestellt werden.
- Tokens sollten nur die notwendigen Gitea-Berechtigungen besitzen.
- Benutzerdefinierte Gitea-URLs müssen validiert werden, um SSRF-Zugriffe auf interne Dienste zu verhindern.
- Für produktive Verbindungen sollte HTTPS verlangt werden.
- Spätere Webhooks benötigen eine Signatur- oder Secret-Prüfung.

## Zusammenspiel mit Slash-Befehlen

`/issue` ist eine Aktion und nicht zwingend ein neuer Eintragstyp. Zwei Varianten sind möglich:

1. `/issue` erstellt das externe Issue und lokal einen Link-Eintrag.
2. `/issue` erstellt lokal eine Aufgabe, die mit dem externen Issue verbunden ist.

Für den MVP wird Variante 1 empfohlen, weil der externe Issue-Link das primäre Ergebnis ist. Vor der Implementierung sollte entschieden werden, ob `/issue` – wie die Typbefehle – nur am Anfang eines Eintrags erlaubt ist.

## Tests

Mindestens erforderlich:

- Parser für `/issue`
- Standard-Repository und Alias-Auflösung
- Titel und mehrzeilige Beschreibung
- erfolgreicher API-Aufruf mit gemockter Gitea-API
- Fehlerantworten und Timeouts
- kein Verlust des lokalen Textes bei Fehlern
- Berechtigungsprüfung für Benutzer und Teams
- sichere Behandlung des Tokens
- API- und UI-Erstellung

## Ausbaustufen

### Stufe 1: Issues erstellen

- eine Gitea-Verbindung pro Benutzer
- Standard-Repository
- `/issue Titel`
- lokaler Link zum erstellten Issue
- robuste Fehlerbehandlung

Geschätzter Aufwand: **1–2 Entwicklungstage**.

### Stufe 2: Mehrere Repositories und Labels

- Repository-Aliase
- Label-Zuordnung
- Team-Verbindungen
- Verbindungstest in den Einstellungen

Geschätzter Gesamtaufwand: **3–5 Entwicklungstage**.

### Stufe 3: Bidirektionale Synchronisation

- geschlossenes Gitea-Issue erledigt die lokale Aufgabe
- erledigte lokale Aufgabe schließt das Gitea-Issue
- Kommentare synchronisieren
- Webhooks
- Schutz vor Synchronisationsschleifen

Geschätzter Aufwand: **1–2 Wochen**.

### Stufe 4: Vollständige Integration

- OAuth statt manueller Tokens
- mehrere Gitea-Instanzen
- Hintergrundjobs und automatische Wiederholungen
- Bearbeiter, Meilensteine und Projekte
- Konfliktbehandlung

Geschätzter Aufwand: **2–3 Wochen**.

## Empfohlener MVP

1. Gitea-URL, Token und Standard-Repository konfigurierbar machen.
2. Repository-Aliase unterstützen.
3. `/issue [alias] Titel` parsen.
4. Restlichen mehrzeiligen Text als Beschreibung verwenden.
5. Issue synchron über die Gitea-API erstellen.
6. Einen lokalen Link-Eintrag mit externer Referenz anlegen.
7. Bei Fehlern einen lokalen Eintrag mit Wiederholungsmöglichkeit behalten.
8. Noch keine automatische Synchronisation oder Webhooks implementieren.

Diese Variante liefert schnell einen praktischen Nutzen und hält Sicherheits-, Synchronisations- und Betriebsaufwand zunächst überschaubar.