docs: spec design vote roadmap #94
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Colin Maudry
@@ -0,0 +1,144 @@
|
||||
# Vote pour les prochaines fonctionnalités (Roadmap) — Design
|
||||
|
||||
Issue : [#94](https://github.com/ColinMaudry/decp.info/issues/94)
|
||||
Date : 2026-06-30
|
||||
|
||||
## Objectif
|
||||
|
||||
Permettre aux abonnés de voter pour les prochaines fonctionnalités depuis une
|
||||
section Roadmap réservée aux abonnés (`/compte/roadmap`). La même roadmap est
|
||||
exposée en lecture seule au public (`/a-propos/roadmap`). Les fonctionnalités
|
||||
sont gérées dans GitHub via des labels ; le changelog du dépôt est affiché en
|
||||
bas des deux pages.
|
||||
|
||||
## Modèle d'attribution des votes
|
||||
|
||||
- Un nouvel abonné reçoit **2 votes** au moment où sa **période d'essai se
|
||||
termine** (passage du statut `trial`/pending à `active`).
|
||||
- Il gagne ensuite **+1 vote par semaine** tant que son abonnement est **actif**.
|
||||
- Les votes ne s'accumulent **pas** pendant une période sans abonnement (gel).
|
||||
- Au **réabonnement**, l'accumulation reprend mais **les 2 votes initiaux ne
|
||||
sont pas re-crédités**.
|
||||
- Un abonné peut voter **plusieurs fois** pour la même fonctionnalité.
|
||||
- Un vote dépensé est **définitif** : pas de retrait possible.
|
||||
|
||||
### Accumulation paresseuse (pas de cronjob)
|
||||
|
||||
État stocké sur la table `subscriptions` (2 colonnes ajoutées par migration) :
|
||||
|
||||
| Colonne | Type | Rôle |
|
||||
| ---------------------- | ---------------------------- | ---------------------------------------------------- |
|
||||
| `votes_balance` | `INTEGER NOT NULL DEFAULT 0` | Solde de votes dépensable |
|
||||
| `votes_credited_until` | `TEXT` (NULL par défaut) | Curseur d'accumulation ; NULL tant que jamais activé |
|
||||
|
||||
Fonction `credit_pending(user_id)`, appelée **au chargement de
|
||||
`/compte/roadmap` et avant chaque vote** :
|
||||
|
||||
1. Charger la ligne d'abonnement de l'utilisateur. Si absente → ne rien faire.
|
||||
2. Si `votes_credited_until` est NULL **et** statut `active` (= fin d'essai
|
||||
atteinte) → créditer les **+2 initiaux**, `votes_credited_until = maintenant`.
|
||||
3. Si `votes_credited_until` posé **et** statut `active` →
|
||||
`semaines = floor((maintenant − votes_credited_until) / 7 jours)` ;
|
||||
si `semaines > 0` : `votes_balance += semaines` et avancer
|
||||
`votes_credited_until` de `semaines × 7 jours`.
|
||||
4. Statut non-`active` → aucun crédit (gel).
|
||||
|
||||
Cette fonction est **idempotente** : recharger la page le même jour ne crédite
|
||||
rien de plus, car le curseur n'avance que par semaines pleines.
|
||||
|
||||
### Gel au désabonnement / réabonnement
|
||||
|
||||
Dans `update_from_webhook` (`src/subscriptions/db.py`) :
|
||||
|
||||
- **Résiliation** (`active` → `cancelled`) : appeler `credit_pending` pour
|
||||
banquer les semaines acquises ; le statut `cancelled` bloque ensuite tout
|
||||
crédit (le curseur reste figé).
|
||||
- **Réabonnement** (`cancelled` → `active`) : remettre
|
||||
`votes_credited_until = maintenant` pour ne pas créditer la période sans
|
||||
abonnement, **sans re-créditer les +2** (curseur non-NULL).
|
||||
|
||||
## Registre des votes émis
|
||||
|
||||
Nouvelle table dans `users.sqlite` :
|
||||
|
||||
```sql
|
||||
CREATE TABLE feature_votes (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
user_id INTEGER NOT NULL,
|
||||
issue_number INTEGER NOT NULL,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
- Une ligne par vote émis (vote multiple = plusieurs lignes).
|
||||
- Décompte d'une fonctionnalité = `COUNT(*)` groupé par `issue_number`.
|
||||
- Décomptes **publics** (visibles sur `/a-propos/roadmap`).
|
||||
|
||||
Migrations ajoutées dans `src/migrations.py` (`_MIGRATIONS`) :
|
||||
|
||||
- ajout de `votes_balance` et `votes_credited_until` sur `subscriptions`
|
||||
- création de la table `feature_votes`
|
||||
|
||||
## Intégration GitHub & cache
|
||||
|
||||
Nouveau module `src/util/roadmap.py` :
|
||||
|
||||
- `fetch_roadmap_issues()`, décoré `@cache.memoize(timeout=3600)` (cache 1 h) :
|
||||
`httpx.get` sur `GET /repos/ColinMaudry/decp.info/issues?state=open`, puis
|
||||
filtrage local par label. Retourne deux listes de dicts
|
||||
`{number, title, html_url}` : les `en cours` et les `mis au vote`.
|
||||
- **Appel anonyme** (pas de `GITHUB_TOKEN`) : suffisant pour un dépôt public
|
||||
avec un cache d'1 heure.
|
||||
- On reste sur `httpx`, déjà dépendance du projet (Dash, `src/utils/data.py`,
|
||||
`src/utils/tracking.py`) — pas d'ajout de `requests`.
|
||||
|
||||
`src/util/roadmap.py` centralise aussi :
|
||||
|
||||
- la récupération des décomptes (`COUNT` groupé depuis `feature_votes`) ;
|
||||
- un constructeur de composants `render_roadmap(editable: bool)` partagé par les
|
||||
deux pages.
|
||||
|
||||
## Pages & navigation
|
||||
|
||||
### Page abonné — `src/pages/compte_roadmap.py`
|
||||
|
||||
- Route `/compte/roadmap`, `require_subscription=True`, via `account_shell`.
|
||||
- À l'entrée : `credit_pending(user_id)`.
|
||||
- Contenu :
|
||||
1. Bandeau « Il te reste **N** votes » (solde courant).
|
||||
2. Section **« En cours »** (label `en cours`) — titres liés vers GitHub, pas
|
||||
de vote.
|
||||
3. Section **« Au vote »** (label `mis au vote`) — triée par votes
|
||||
décroissants ; chaque fonctionnalité affiche son décompte + un bouton
|
||||
« Voter » (désactivé si solde = 0).
|
||||
4. **Changelog** (`CHANGELOG.md` rendu via `dcc.Markdown`).
|
||||
|
||||
Action de vote : vérifier `votes_balance > 0`, décrémenter `votes_balance`,
|
||||
insérer une ligne `feature_votes`, rafraîchir l'affichage.
|
||||
|
||||
### Page publique — `src/pages/a_propos/roadmap.py`
|
||||
|
||||
- Route `/a-propos/roadmap`, via `apropos_shell`.
|
||||
- Identique mais `render_roadmap(editable=False)` : décomptes publics visibles,
|
||||
**aucun bouton**, pas de bandeau de solde.
|
||||
|
||||
### Navigation
|
||||
|
||||
- Ajout d'une entrée `roadmap` dans `SECTIONS` de `_compte_shell.py`
|
||||
(`require_subscription=True`).
|
||||
- Ajout d'une entrée `roadmap` dans `SECTIONS` de `_apropos_shell.py`.
|
||||
|
||||
## Lien version & changelog
|
||||
|
||||
- Dans `src/app.py` (~ligne 194), le lien du numéro de version pointe vers
|
||||
`/a-propos/roadmap` au lieu de l'URL GitHub du `CHANGELOG.md`.
|
||||
- Lecture de `CHANGELOG.md` (racine du dépôt) rendue via `dcc.Markdown`,
|
||||
partagée par les deux pages.
|
||||
|
||||
## Hors périmètre (YAGNI)
|
||||
|
||||
- Pas de cronjob / timer pour l'accumulation.
|
||||
- Pas de retrait de vote.
|
||||
- Pas de `GITHUB_TOKEN`.
|
||||
- Pas de gestion d'écriture vers GitHub (les fonctionnalités restent gérées
|
||||
manuellement via les labels GitHub).
|
||||
Reference in New Issue
Block a user