# Acteurs de la plateforme — qui peut faire quoi, et comment

Ce document liste, pour chaque acteur du système, ce qu'il peut faire et par
quel moyen concret (page du site, endpoint de l'API, ou action humaine hors
logiciel). Il complète [`docs/scoring.md`](./scoring.md) (formule de score),
[`docs/architecture.md`](./architecture.md) (vue d'ensemble, infrastructure)
et [`SPEC.md`](../SPEC.md) (cahier des charges complet).

Il y a 4 acteurs : **membre**, **administrateur**, **visiteur public**, et
**organisateur du wallet**. Contrairement aux versions antérieures de ce
document, il n'y a **plus de process automatisé serveur** pour la collecte
de minage — c'est désormais l'administrateur qui la déclenche lui-même
depuis sa propre machine (voir §2 et §5).

---

## 1. Membre

Un membre de l'association, inscrit sur le site. Le module miner tourne en
tâche de fond sur sa machine — via l'application avec icône dans la barre
des tâches (voir `context-claude-code/miner-existant/tray/`), qui pilote le
moteur `mine` existant sans que le membre ait jamais besoin d'un terminal.

| Il peut... | Comment |
|---|---|
| S'inscrire (email + mot de passe + pseudonyme) | Page `/register` → `POST /auth/register.php`. Génère automatiquement sa clé d'identification unique. |
| Se connecter | Page `/login` → `POST /auth/login.php` (renvoie un token JWT stocké côté navigateur) |
| Voir son profil (ancienneté, statut KYC) | `/dashboard` → `GET /auth/me.php` |
| Télécharger son application de minage, prête à l'emploi | Bouton (Windows/Linux/macOS) sur `/dashboard` → `GET /auth/miner-download.php?os=...` : un seul zip contenant le binaire déjà compilé (adresse de l'association codée en dur dedans, voir `tray/README.md`) + son `member.token` individuel + des instructions. Rien à assembler soi-même. |
| Régler la puissance de minage utilisée, sans terminal ni fichier à éditer | Icône près de l'horloge (barre des tâches) → petite page de réglages avec un curseur : plus de puissance = machine plus chaude mais demande d'aide mieux classée (le temps de minage et la puissance comptent dans le score, voir `docs/scoring.md`) ; moins de puissance = moins de chaleur, classement moins avantageux |
| Laisser l'icône se relancer toute seule après un redémarrage (ou le désactiver) | Activé automatiquement au premier lancement ; case à cocher dans le menu de l'icône pour désactiver |
| Déposer une demande d'aide (montant + message), **une par tranche** | Formulaire sur `/dashboard` → `POST /requests/index.php` (409 si une demande existe déjà sur la tranche en cours) |
| Voir les demandes de la tranche en cours pour voter en connaissance de cause | `/dashboard` → `GET /requests/index.php` (réservé aux membres connectés — les messages personnels ne sont pas publics) |
| Voter pour une demande (facultatif, **un vote par tranche**, jamais pour sa propre demande) | Bouton "Voter" sur `/dashboard` → `POST /votes/index.php` (409 si déjà voté sur cette tranche) |
| Voir l'historique de ses propres demandes | `/dashboard` → `GET /requests/me.php` |
| Consulter la transparence publique (comme n'importe qui, voir §3) | `/transparency` |

Ce qu'un membre **ne peut pas faire** : voir le message d'une demande d'aide
sans être connecté, voter plusieurs fois, déclencher lui-même le calcul de
score, de trésorerie ou de distribution, ni clôturer une tranche (réservé à
l'administrateur).

---

## 2. Administrateur (organisateur de l'association)

Le compte porte le champ `is_admin = true` en base. **Il n'existe pas
d'endpoint pour le devenir soi-même** (sécurité) : c'est un choix delibéré —
il faut positionner ce flag directement en base de données au moment de créer
le premier compte administrateur, par exemple :

```sql
UPDATE members SET is_admin = 1 WHERE email = 'organisateur@association.example';
```

| Il peut... | Comment |
|---|---|
| Se connecter à l'interface d'administration | Page `/admin/login` (même mécanisme que le login membre — `POST /auth/login.php` — c'est le flag `is_admin`, vérifié côté serveur, qui donne l'accès réel) → `/admin` |
| Récupérer les métriques de minage collectées auprès du pool | **Depuis sa propre machine**, jamais depuis le site : `python admin-tools/collect_mining.py --api-base-url ... --wallet ...` (voir §5 et `admin-tools/README.md`). Peut être relancé aussi souvent qu'il veut pendant une tranche ouverte. |
| Calculer les scores de la tranche pour tous les demandeurs | Bouton sur `/admin` → `POST /scoring/compute.php?tranche_id=...` |
| Calculer la trésorerie de la tranche (frais brut/taux/net) | Formulaire sur `/admin` → `POST /treasury/compute.php?tranche_id=...&cagnotte_brute=...` |
| Lancer le moteur de distribution en cascade | Case à cocher + bouton sur `/admin` → `POST /distribution/run.php?tranche_id=...&dry_run=true` — **dry-run coché par défaut**, il faut le décocher explicitement pour que le plan soit persisté et journalisé dans l'audit log. Un run réel **clôture la tranche et en ouvre une nouvelle** automatiquement. |
| Consulter la feuille de paie (adresses des bénéficiaires) | Bouton sur `/admin` → `GET /distribution/payout-sheet.php?tranche_id=...` |
| Confirmer qu'un paiement a réellement été envoyé (après l'avoir fait manuellement depuis son propre wallet, voir §4) | Formulaire sur `/admin` → `POST /distribution/confirm.php?tranche_id=...&distribution_id=...&tx_hash=...` (idempotent) |
| Consulter l'audit log et vérifier l'intégrité de la chaîne | Bouton sur `/admin` (mêmes données que `/audit/log.php` et `/audit/verify.php`, publiques) |

`/admin/login` n'est actuellement pas lié depuis la navigation principale
(accès par URL directe) — l'emplacement exact pourra être rendu
configurable/moins découvrable plus tard si besoin. Les mêmes actions
restent aussi utilisables en ligne de commande (`curl`).

**Ce que l'administrateur ne peut jamais faire depuis le site** : envoyer
réellement des fonds, ni interroger lui-même le pool de minage depuis le
serveur web (ce dernier n'a d'ailleurs plus aucun mécanisme pour le faire —
voir §5). Le serveur web calcule et publie qui doit recevoir quoi, mais n'a
jamais la main sur la clé privée du wallet (séparation calcul/exécution,
SPEC.md §5) — voir l'acteur suivant.

---

## 3. Visiteur public (connecté ou non, même non-membre)

N'importe qui peut consulter la transparence de l'association, sans compte.

| Il peut voir... | Comment |
|---|---|
| La liste des tranches passées et en cours | `/transparency` → `GET /tranches/index.php` |
| La cagnotte de la tranche (brut, taux de frais appliqué, net, reliquat) | `/transparency` → `GET /treasury/index.php?tranche_id=...` |
| Le détail complet du score de chaque membre (chaque composante, pas juste le total) | `/transparency` → `GET /scoring/index.php?tranche_id=...` |
| La liste des bénéficiaires de la tranche et leur statut de paiement | `/transparency` → `GET /distribution/index.php?tranche_id=...` |
| L'intégralité de l'audit log (inscriptions, minage, demandes, votes, scores, décaissements) | `GET /audit/log.php` |
| Une vérification cryptographique que l'audit log n'a pas été altéré | `GET /audit/verify.php` |
| La documentation publique de la formule de score | `/docs/scoring.md` (frontend) ou [`docs/scoring.md`](./scoring.md) (dépôt) |

Cette transparence totale est une exigence non négociable du SPEC (§5) :
formule de score et moteur de distribution publics, frais jamais silencieux.

---

## 4. Organisateur du wallet Monero (rôle humain, hors logiciel web)

Ce n'est pas un compte du site : c'est la personne qui détient la seed du
wallet unique de l'association, sur sa machine, hors du serveur web
(SPEC.md §2 et §5 : pas de multisig, mais protection renforcée de cette
machine puisque c'est un point de défaillance unique).

| Elle peut... | Comment |
|---|---|
| Récupérer en une commande la feuille de paie de la tranche (adresses personnelles + montants à verser, *réservé admin* — pas la même vue que le public en §3) | `GET /distribution/payout-sheet.php?tranche_id=...`, consommé automatiquement par `organizer-tools/pay_month.py` |
| Envoyer réellement les fonds à chaque bénéficiaire, sur son adresse Monero personnelle | **Script `organizer-tools/pay_month.py`**, exécuté sur sa propre machine, qui pilote son `monero-wallet-rpc` local (un `transfer` individuel par bénéficiaire) — voir [`organizer-tools/README.md`](../organizer-tools/README.md) |
| Confirmer chaque envoi auprès du serveur | Fait automatiquement par le script (`POST /distribution/confirm.php`), pas besoin d'action manuelle séparée |
| Tester sur un petit sous-ensemble avant un envoi massif (le nombre de bénéficiaires peut aller de 1 à plusieurs centaines de milliers) | `pay_month.py --no-dry-run --limit 3` |
| Relancer sans risque après une panne ou une coupure réseau en plein envoi | Le script journalise chaque envoi en local *avant* de confirmer côté serveur — jamais de double paiement (voir le détail dans `organizer-tools/README.md`) |

Dans la pratique actuelle, c'est souvent la même personne physique que
l'administrateur (§2), mais ce sont deux *rôles* distincts : l'un agit dans
le logiciel web, l'autre agit dans un outil complètement séparé qui ne
communique jamais avec le serveur au-delà de ces deux appels HTTP.

---

## 5. Collecte des métriques de minage — un script local, pas un acteur automatisé

Contrairement aux versions antérieures de ce système, il n'y a **plus de
process serveur** qui interroge le pool en continu. La collecte est un
**geste explicite de l'administrateur**, depuis sa propre machine :

| Étape | Comment |
|---|---|
| Lister les membres actifs et leur clé | `admin-tools/collect_mining.py` appelle `GET /auth/members-actifs.php` (réservé admin) |
| Interroger le pool par clé de membre exacte | Appels directs à `supportxmr.com` (ou équivalent) — `stats/{clé}` pour le travail cumulé, `chart/hashrate/{clé}` pour le temps de minage récent (voir `docs/architecture.md` §5.2 pour les pièges empiriques de cette API) |
| Pousser le résultat au serveur | `POST /mining/import.php` (réservé admin) — le serveur se contente d'enregistrer, il ne calcule ni n'interroge rien lui-même |

Ce script peut être relancé **aussi souvent que l'administrateur le
souhaite** pendant une tranche ouverte — chaque passage ne mesure que le
delta depuis le passage précédent, sans double-comptage. Recommandé : le
relancer une dernière fois juste avant de calculer le score (§2), pour
capter les données les plus récentes. Voir `admin-tools/README.md` pour le
détail.

---

## Résumé visuel

```
Membre ──────► dépose une demande, vote, mine

Administrateur ──► pousse les métriques de minage (admin-tools, sur sa machine)
                    │
                    ▼
                    calcule trésorerie → scores → distribution (dry-run puis réel)
                    │
                    ▼
           publie la liste des bénéficiaires ; une distribution réelle
           clôture la tranche et en ouvre une nouvelle
                    │
                    ▼
Organisateur wallet ──► pay_month.py (sa machine) : envoie les fonds via
                         son monero-wallet-rpc local → confirme automatiquement

Visiteur public ──► consulte tout, à tout moment (transparence)
```