docs : add Gitea integration design spec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/superpowers/specs/2026-03-13-gitea-integration-design.md

@@ -0,0 +1,124 @@
+# Intégration Gitea — Design Spec
+
+## Objectif
+
+Lier les tickets Lesstime à Gitea pour :
+- Créer une branche depuis un ticket (avec choix du type : feature, fix, refactor, etc.)
+- Voir les branches, commits, PRs et statut CI liés à un ticket
+- Le tout à la demande (pas de webhook, pas de cron, pas de stockage git en base)
+
+## Décisions
+
+| Question | Décision |
+|----------|----------|
+| Interaction | Depuis Lesstime uniquement (bouton + affichage) |
+| Repos | Un projet = un repo Gitea |
+| Nommage branches | `<type>/PROJ-42-titre-en-slug` (type choisi par l'utilisateur) |
+| Détection commits | Par la branche (tous les commits d'une branche liée au ticket) |
+| Données affichées | Branches + commits + PRs + statut CI/CD |
+| Config serveur | Globale (admin) : URL + token API |
+| Config repo | Par projet : owner + repo name |
+| Synchronisation | À la demande (appel API Gitea en temps réel) |
+
+## Architecture
+
+### Backend
+
+#### Configuration globale — table `Setting`
+
+Nouvelle entité `Setting` (clé-valeur) pour stocker :
+- `gitea_url` — URL de l'instance Gitea (ex: `https://git.malio.fr`)
+- `gitea_token` — Token API Gitea (accès repos)
+
+Alternative : utiliser `config/reference.php` avec des variables d'environnement. La table `Setting` est préférable car configurable depuis l'admin sans redéploiement.
+
+#### Entité `Project` — nouveaux champs
+
+```
+gitea_owner: string|null  (ex: "malio")
+gitea_repo: string|null   (ex: "lesstime")
+```
+
+Nullable car tous les projets ne sont pas forcément liés à un repo.
+
+#### Service `GiteaApiService`
+
+Service Symfony qui encapsule les appels HTTP vers l'API Gitea REST v1.
+
+Méthodes :
+- `listRepositories(): array` — liste les repos accessibles (pour sélection dans le projet)
+- `createBranch(project, task, type, baseBranch): string` — crée une branche `<type>/CODE-NUM-slug` à partir d'une branche de base
+- `listBranches(project, taskCode): array` — liste les branches matchant le pattern `*/CODE-NUM*`
+- `listCommits(project, branch): array` — liste les commits d'une branche
+- `listPullRequests(project, taskCode): array` — liste les PRs dont la branche source matche le code ticket
+- `getPullRequestChecks(project, prNumber): array` — statut CI/CD d'une PR
+
+Le service utilise `HttpClientInterface` de Symfony. Le token est envoyé en header `Authorization: token <gitea_token>`.
+
+#### Endpoints API Platform
+
+Nouveaux endpoints (custom operations ou controllers si nécessaire) :
+
+- `GET /api/settings/gitea` — récupérer la config Gitea (admin only)
+- `PUT /api/settings/gitea` — sauvegarder la config Gitea (admin only)
+- `GET /api/gitea/repositories` — lister les repos disponibles (pour config projet)
+- `POST /api/tasks/{id}/gitea/branches` — créer une branche pour un ticket
+- `GET /api/tasks/{id}/gitea/info` — récupérer branches + commits + PRs + CI pour un ticket
+
+### Frontend
+
+#### Admin — Config Gitea
+
+Nouveau tab ou section dans l'admin pour configurer :
+- URL du serveur Gitea
+- Token API
+- Bouton "Tester la connexion"
+
+#### ProjectDrawer — Config repo
+
+Ajout de champs dans le drawer de projet :
+- Sélecteur de repo Gitea (dropdown alimenté par `GET /api/gitea/repositories`)
+- Affiche `owner/repo` une fois sélectionné
+
+#### TaskModal — Section Git
+
+Nouvelle section dans la TaskModal (visible si le projet a un repo configuré) :
+
+**Bouton "Créer une branche"** :
+- Sélecteur de type : `feature`, `fix`, `refactor`, `hotfix`, `chore`
+- Sélecteur de branche de base (default: branche par défaut du repo)
+- Preview du nom : `feature/PROJ-42-titre-de-la-tache`
+- Bouton de confirmation
+
+**Affichage des infos Git** :
+- Liste des branches liées (avec statut : active / mergée / supprimée)
+- Pour chaque branche : derniers commits (hash court, message, auteur, date)
+- PRs associées (titre, statut : open/merged/closed, reviewers)
+- Statut CI/CD par PR (checks : success/failure/pending)
+- Liens directs vers Gitea pour chaque élément
+
+### Sécurité
+
+- Le token Gitea est stocké chiffré en base (ou au minimum non exposé dans les réponses API)
+- L'endpoint `GET /api/settings/gitea` retourne l'URL mais masque le token (ex: `****`)
+- Seuls les admins peuvent configurer le serveur Gitea
+- Les utilisateurs authentifiés peuvent créer des branches et voir les infos git
+
+## API Gitea — Endpoints utilisés
+
+| Action | Méthode Gitea API |
+|--------|-------------------|
+| Lister repos | `GET /api/v1/repos/search` |
+| Lister branches | `GET /api/v1/repos/{owner}/{repo}/branches` |
+| Créer branche | `POST /api/v1/repos/{owner}/{repo}/branches` |
+| Lister commits | `GET /api/v1/repos/{owner}/{repo}/commits?sha={branch}` |
+| Lister PRs | `GET /api/v1/repos/{owner}/{repo}/pulls?state=all` |
+| Statut CI | `GET /api/v1/repos/{owner}/{repo}/commits/{sha}/statuses` |
+
+## Hors scope
+
+- Webhooks Gitea → Lesstime
+- Stockage des commits/PRs en base
+- Création de PR depuis Lesstime
+- Lien multi-repo par projet
+- Synchronisation périodique (cron/polling)