Restore desktop navigation and refine layouts
This commit is contained in:
rucki
@@ -0,0 +1,224 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user