docs(research): API Gitea endpoints, pagination, auth, cas limites

chore(workflow): complete step 4, start step 5

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

.claude/workflow-progress.md

@@ -10,7 +10,7 @@
 | Version courante | v1.0.0 |
 | Track | major-initial |
 | Phase courante | 1 — FRAMING |
-| Etape courante | 4 |
+| Etape courante | 5 |
 | workflow_version | v1.0 |
 
 ---
@@ -22,8 +22,8 @@
 | 1 | Discovery | done | 2026-03-10 | /forge --discovery | Auto (synthesis.md existe) | step_1: done, deliverable: docs/discovery/synthesis.md |
 | 2 | Creation projet | done | 2026-03-10 | forge | Auto (fichiers existent) | step_2: done, files_created: 14 |
 | 3 | Specs | done | 2026-03-10 | - | Auto (descriptif.md existe avec contexte, objectifs, perimetre, contraintes) | step_3: done |
-| 4 | Recherche | in_progress | 2026-03-10 | researcher | Auto (research.md existe) | |
-| 5 | Roadmap | en_attente | | - | Auto (Gitea milestones + issues created) | |
+| 4 | Recherche | done | 2026-03-10 | researcher | Auto (research.md existe) | step_4: done, topics_researched: 6 (auth, endpoints, pagination, strategie, cas limites, decisions) |
+| 5 | Roadmap | in_progress | 2026-03-10 | - | Auto (Gitea milestones + issues created) | |
 
 ## Phase 2 — DEV (v1.0.0)
 
@@ -71,6 +71,7 @@
 | 2026-03-10 | step 1 done | Discovery synthesis produite via /forge |
 | 2026-03-10 | step 2 done | Structure projet creee via /forge |
 | 2026-03-10 | step 3 done | descriptif.md complet (contexte, objectifs, perimetre, contraintes) |
+| 2026-03-10 | step 4 done | Recherche API Gitea : endpoints, pagination, auth, cas limites |
 
 ## Versions completees
 

docs/technical/research.md

@@ -2,4 +2,163 @@
 
 # Recherche technique — gitea-dashboard
 
-<!-- A completer a l'etape 4 par le researcher -->
+Date : 2026-03-10 | Gitea 1.25.1 | Source : swagger.v1.json + docs.gitea.com
+
+## Contexte
+
+Le dashboard CLI doit afficher pour chaque repo Gitea : le nombre d'issues ouvertes, la derniere release, et l'etat des milestones. Cette recherche identifie les endpoints API necessaires, la strategie de pagination, le format d'authentification, et les cas limites.
+
+---
+
+## 1. Authentification
+
+### Format recommande
+
+```
+Authorization: token <GITEA_TOKEN>
+```
+
+Le header `Authorization` avec le prefixe `token ` (suivi d'un espace) est la methode recommandee. Les anciennes methodes (query parameter `?token=` ou `?access_token=`) sont **deprecated depuis Gitea 1.23** et seront supprimees.
+
+**Source** : schema `securityDefinitions` du swagger + https://docs.gitea.com/development/api-usage
+
+---
+
+## 2. Endpoints API necessaires
+
+### 2.1 Liste des repos de l'utilisateur
+
+**Endpoint** : `GET /api/v1/user/repos`
+
+Retourne les repos dont l'utilisateur authentifie est proprietaire.
+
+| Parametre | Type | Description |
+|-----------|------|-------------|
+| `page` | integer | Numero de page (defaut : 1) |
+| `limit` | integer | Elements par page (defaut : 50, max : 50) |
+
+**Reponse** : Array de `Repository`
+
+**Champs cles** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `id` | int64 | Identifiant unique |
+| `name` | string | Nom du repo |
+| `full_name` | string | `owner/name` |
+| `description` | string | Description |
+| `fork` | boolean | Est un fork |
+| `archived` | boolean | Est archive |
+| `mirror` | boolean | Est un miroir |
+| `open_issues_count` | int64 | Issues ouvertes (inclut les PRs) |
+| `open_pr_counter` | int64 | PRs ouvertes (champ separe) |
+| `release_counter` | int64 | Nombre total de releases |
+| `owner.login` | string | Login du proprietaire |
+| `updated_at` | datetime | Derniere mise a jour |
+
+**Alternative** : `GET /api/v1/repos/search` retourne tous les repos visibles (pas seulement ceux de l'utilisateur). Reponse enveloppee dans `{"ok": true, "data": [...]}`.
+
+### 2.2 Derniere release par repo
+
+**Endpoint** : `GET /api/v1/repos/{owner}/{repo}/releases/latest`
+
+Retourne la release la plus recente (hors draft et pre-release). Un seul objet, pas de pagination.
+
+**Champs cles** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `tag_name` | string | Nom du tag git |
+| `name` | string | Titre de la release |
+| `published_at` | datetime | Date de publication |
+| `prerelease` | boolean | Est une pre-release |
+
+**Retourne HTTP 404** si le repo n'a aucune release.
+
+### 2.3 Milestones par repo
+
+**Endpoint** : `GET /api/v1/repos/{owner}/{repo}/milestones`
+
+| Parametre | Type | Description |
+|-----------|------|-------------|
+| `state` | string | `open`, `closed`, `all` |
+| `page` | integer | Numero de page |
+| `limit` | integer | Elements par page |
+
+**Champs cles** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `title` | string | Nom du milestone |
+| `state` | StateType | `open` ou `closed` |
+| `open_issues` | int64 | Issues ouvertes dans le milestone |
+| `closed_issues` | int64 | Issues fermees dans le milestone |
+| `due_on` | datetime | Date d'echeance |
+
+Le modele contient deja `open_issues` et `closed_issues` — progression calculable sans appel supplementaire.
+
+---
+
+## 3. Pagination
+
+| Parametre | Defaut | Maximum |
+|-----------|--------|---------|
+| `page` | 1 | - |
+| `limit` | 50 | 50 |
+
+### Headers de reponse
+
+| Header | Description |
+|--------|-------------|
+| `X-Total-Count` | Nombre total d'elements |
+| `Link` | URLs de navigation (`rel="next"`, `rel="last"`) |
+
+### Strategie recommandee
+
+1. Premiere requete avec `?limit=50&page=1`
+2. Lire `X-Total-Count` dans les headers
+3. Si `total > limit` : calculer le nombre de pages, lancer les requetes suivantes
+4. Alternative simple : boucler tant que `len(results) == limit`
+
+**Source** : https://docs.gitea.com/development/api-usage (section Pagination)
+
+---
+
+## 4. Strategie d'appels
+
+Pour N repos :
+
+| Donnee | Appels | Endpoint |
+|--------|--------|----------|
+| Liste des repos | ceil(N/50) | `GET /user/repos` |
+| Derniere release | N | `GET /repos/{o}/{r}/releases/latest` |
+| Milestones | N | `GET /repos/{o}/{r}/milestones` |
+| **Total** | **ceil(N/50) + 2N** | |
+
+Issues ouvertes : derivees de `open_issues_count - open_pr_counter` du modele Repository (zero appel supplementaire).
+
+**Parallelisation** : `concurrent.futures.ThreadPoolExecutor` avec 5-10 workers. La lib `requests` est thread-safe.
+
+---
+
+## 5. Cas limites
+
+| Cas | Comportement API | Gestion |
+|-----|-----------------|---------|
+| Repo sans release | `/releases/latest` retourne 404 | Capturer, afficher "—" |
+| Repo sans milestone | `/milestones` retourne `[]` | Tableau vide, rien a afficher |
+| Repo sans issues | `open_issues_count` = 0 | Comportement standard |
+| Repo fork | `fork` = true | Afficher avec indicateur visuel |
+| Repo archive | `archived` = true | Afficher avec indicateur visuel |
+| `open_issues_count` inclut PRs | Herite de GitHub | Calculer `open_issues_count - open_pr_counter` |
+
+---
+
+## 6. Decisions recommandees
+
+| # | Decision | Recommandation | Justification |
+|---|----------|---------------|---------------|
+| 1 | Endpoint repos | `GET /user/repos` | Plus simple, reponse directe, suffisant pour v1 |
+| 2 | Comptage issues | `open_issues_count - open_pr_counter` | Zero appel supplementaire |
+| 3 | Forks/archives | Tout afficher avec indicateurs | Exhaustivite, pas de filtre en v1 |
+| 4 | Parallelisation | ThreadPoolExecutor (5 workers) | Acceptable pour < 200 repos |