gitea-dashboard/docs/technical/research.md

<!-- Type: explanation (Diataxis). Style: discursif, comparaisons argumentees, sources citees. -->

# 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 <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 |