docs(v1.0.0): version plan and ADR
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
sylvain
@@ -2,4 +2,144 @@
|
||||
|
||||
# Architecture — gitea-dashboard
|
||||
|
||||
<!-- A completer a l'etape 6 par l'architect -->
|
||||
## 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)
|
||||
|
||||
@@ -16,3 +16,33 @@
|
||||
- Pas de framework CLI lourd (argparse suffit si besoin)
|
||||
- rich offre des tableaux et couleurs sans configuration complexe
|
||||
- Dependance a requests (pas de client async, acceptable pour un affichage unique)
|
||||
|
||||
## ADR-002 : 4 modules maximum (client, collector, display, cli)
|
||||
|
||||
**Date** : 2026-03-10
|
||||
**Statut** : accepte
|
||||
|
||||
**Contexte** : Definir la granularite des modules Python pour un projet simple (dashboard CLI).
|
||||
|
||||
**Decision** : Limiter a 4 modules avec des responsabilites claires : `client.py` (API), `collector.py` (agregation), `display.py` (formatage), `cli.py` (entree).
|
||||
|
||||
**Consequences** :
|
||||
- Separation des responsabilites sans over-engineering
|
||||
- Chaque module est testable independamment
|
||||
- Un fichier = une responsabilite = un jeu de tests
|
||||
- Si le projet grandit, chaque module peut evoluer independamment
|
||||
|
||||
## ADR-003 : Pas de parallelisation en v1
|
||||
|
||||
**Date** : 2026-03-10
|
||||
**Statut** : accepte
|
||||
|
||||
**Contexte** : La collecte de donnees necessite N appels par repo (release + milestones). La parallelisation (ThreadPoolExecutor) est possible mais ajoute de la complexite.
|
||||
|
||||
**Decision** : V1 en sequentiel. La parallelisation est differee a v1.1+.
|
||||
|
||||
**Consequences** :
|
||||
- Code plus simple a ecrire, deboguer et tester
|
||||
- Temps de reponse acceptable pour < 20 repos (estimee < 10s)
|
||||
- Pas de problemes de concurrence
|
||||
- Facile a ajouter plus tard sans changer les interfaces (le collecteur est le seul point d'appel)
|
||||
|
||||
Reference in New Issue
Block a user