146 lines
5.7 KiB
Markdown
146 lines
5.7 KiB
Markdown
<!-- Type: reference (Diataxis). Style: factuel, exhaustif, structure par le code. Pas de tutoriel ici. -->
|
|
|
|
# Architecture — gitea-dashboard
|
|
|
|
## Vue d'ensemble
|
|
|
|
```
|
|
gitea-dashboard
|
|
==============
|
|
|
|
Terminal Application Gitea API
|
|
-------- ----------- ---------
|
|
|
|
+------------------+
|
|
$ gitea-dashboard | cli.py |
|
|
------------------->| - lit env vars |
|
|
| - configure |
|
|
| - gere erreurs |
|
|
+--------+---------+
|
|
|
|
|
v
|
|
+------------------+
|
|
| collector.py |
|
|
| - orchestre la |
|
|
| collecte | +------------------+
|
|
| - agrege en |---->| client.py |
|
|
| RepoData | | - auth token |-----> GET /api/v1/user/repos
|
|
+--------+---------+ | - pagination |-----> GET /repos/{o}/{r}/releases/latest
|
|
| | - erreurs HTTP |-----> GET /repos/{o}/{r}/milestones
|
|
v +------------------+
|
|
+------------------+
|
|
| display.py |
|
|
| - tableau repos |
|
|
<-------------------| - milestones |
|
|
Output Rich | - indicateurs |
|
|
(tableaux, +------------------+
|
|
couleurs)
|
|
```
|
|
|
|
## Composants
|
|
|
|
### cli.py — Point d'entree
|
|
|
|
Responsabilite : orchestration du flux principal.
|
|
|
|
- Lit les variables d'environnement `GITEA_URL` (defaut: `http://192.168.0.106:3000`) et `GITEA_TOKEN` (requis)
|
|
- Valide la configuration, affiche un message d'erreur clair si manquante
|
|
- Cree le `GiteaClient`, lance la collecte, passe les resultats a l'affichage
|
|
- Gere les erreurs globales (connexion refusee, timeout, erreurs API)
|
|
- Enregistre comme entry point : `gitea-dashboard = "gitea_dashboard.cli:main"`
|
|
|
|
### client.py — Client API Gitea
|
|
|
|
Responsabilite : communication avec l'API REST Gitea.
|
|
|
|
- Authentification via header `Authorization: token <GITEA_TOKEN>`
|
|
- Methode interne `_get_paginated()` pour la pagination transparente (limit=50, boucle tant que page pleine)
|
|
- Methodes publiques : `get_repos()`, `get_latest_release(owner, repo)`, `get_milestones(owner, repo)`
|
|
- Gestion du 404 sur `/releases/latest` (retourne `None`)
|
|
- Utilise `requests.Session` pour reutiliser les connexions HTTP
|
|
|
|
### collector.py — Collecteur de donnees
|
|
|
|
Responsabilite : agregation des donnees de tous les repos.
|
|
|
|
- Definit le dataclass `RepoData` qui normalise les donnees d'un repo
|
|
- Calcul des issues ouvertes reelles : `open_issues_count - open_pr_counter`
|
|
- Pour chaque repo : enrichit avec la derniere release et les milestones ouvertes
|
|
- Fonction principale `collect_all(client) -> list[RepoData]`
|
|
|
|
### display.py — Affichage Rich
|
|
|
|
Responsabilite : formatage et rendu terminal.
|
|
|
|
- Tableau principal : nom du repo, indicateurs visuels ([F]ork, [A]rchive, [M]irror), issues ouvertes, derniere release (tag + date)
|
|
- Section milestones : affichee uniquement pour les repos ayant des milestones ouvertes, avec progression (closed/total)
|
|
- Accepte un parametre `Console` optionnel pour l'injection dans les tests
|
|
- Fonction principale `render_dashboard(repos, console=None)`
|
|
|
|
## Structure du projet
|
|
|
|
```
|
|
gitea-dashboard/
|
|
CLAUDE.md # Instructions projet
|
|
pyproject.toml # Config build, deps, entry point
|
|
README.md # Documentation utilisateur
|
|
src/
|
|
gitea_dashboard/
|
|
__init__.py # Docstring du package
|
|
cli.py # Point d'entree, config, orchestration
|
|
client.py # Client API Gitea (auth, pagination)
|
|
collector.py # Agregation des donnees repos
|
|
display.py # Formatage Rich (tableaux, couleurs)
|
|
tests/
|
|
__init__.py
|
|
test_client.py # Tests client API (mocks requests)
|
|
test_collector.py # Tests collecteur (mocks client)
|
|
test_display.py # Tests affichage (capture console)
|
|
test_cli.py # Tests integration CLI (mocks env)
|
|
docs/
|
|
plans/
|
|
v1.0.0-plan.md # Plan de version
|
|
technical/
|
|
ARCHITECTURE.md # Ce fichier
|
|
decisions.md # ADR
|
|
research.md # Recherche technique API
|
|
discovery/
|
|
synthesis.md # Synthese discovery
|
|
project/
|
|
descriptif.md # Descriptif du projet
|
|
```
|
|
|
|
## Flux de donnees principal
|
|
|
|
```
|
|
1. cli.main()
|
|
|
|
|
+-- Lit os.environ["GITEA_TOKEN"] et os.environ.get("GITEA_URL", default)
|
|
|
|
|
+-- GiteaClient(url, token)
|
|
|
|
|
+-- collect_all(client)
|
|
| |
|
|
| +-- client.get_repos() -> list[dict] (pagine)
|
|
| |
|
|
| +-- Pour chaque repo:
|
|
| +-- client.get_latest_release(owner, name) -> dict | None
|
|
| +-- client.get_milestones(owner, name) -> list[dict]
|
|
| +-- RepoData(...)
|
|
|
|
|
+-- render_dashboard(repos)
|
|
|
|
|
+-- Rich Table (repos)
|
|
+-- Rich Table (milestones)
|
|
+-- Console.print()
|
|
```
|
|
|
|
## Decisions architecturales
|
|
|
|
Les decisions sont tracees dans `docs/technical/decisions.md` (format ADR).
|
|
|
|
Decisions cles pour v1.0.0 :
|
|
- **ADR-001** : Stack Python + requests + rich
|
|
- **ADR-002** : 4 modules maximum (client, collector, display, cli)
|
|
- **ADR-003** : Pas de parallelisation en v1 (sequentiel, plus simple a deboguer)
|