diff --git a/.claude/workflow-progress.md b/.claude/workflow-progress.md index cd79085..3d82e58 100644 --- a/.claude/workflow-progress.md +++ b/.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 diff --git a/docs/technical/research.md b/docs/technical/research.md index f9cd272..60775ef 100644 --- a/docs/technical/research.md +++ b/docs/technical/research.md @@ -2,4 +2,163 @@ # Recherche technique — gitea-dashboard - +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 +``` + +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 |