groupe-meditation/README.md

# Groupe Méditation — Application PWA

**District 87-16 · Région 87 · Alcooliques anonymes**

Application mobile-first pour la gestion des groupes AA. 1 module = 1 tâche.

## Architecture

| Couche | Technologie |
|--------|-------------|
| Frontend | React 18 + Vite (PWA installable) |
| UI | Tailwind CSS (mobile-first) |
| État | Zustand |
| Backend | FastAPI (Python) async |
| DB | PostgreSQL + SQLAlchemy async |
| Auth | JWT 30 jours + bcrypt 12 rounds (prénom + PIN) |
| PDF | WeasyPrint |
| Serveur | NGINX (statiques + reverse proxy HTTPS) |

## Modules

### Consultation — Tous les membres

- **C1** Rapports PDF — finances, PV, résolutions, rapport complet
- **C2** Événements — anniversaires de sobriété, événements et résolutions
- **C4** Littérature — inventaire avec prix, alerte stock bas
- **C5** Gouvernance — décisions du groupe, propositions, résolutions, nominations et contributions
- **C7** Mon profil — modifier, changer PIN, notifications
- **C9** Postes à pourvoir — postes vacants, candidatures

### Saisie hebdomadaire (S1-S5)

- **S0** Réunion hebdomadaire — formulaire regroupé pour rapport, collecte, jeton et littérature
- **S1** Collecte 7e Tradition — réservé aux postes exécutifs
- **S1T** Trésorerie — soldes (banque + encaisse + réserves affectées), réception des collectes et ventes de littérature, registre détaillé des transactions, opérations bancaires (dépôt/retrait/relevé)
- **S2** Remise de jeton — 9 types, historique
- **S3** Vente littérature — stock auto-décrémenté, montant à remettre au trésorier
- **S4** Rapport de réunion — thème + annonces
- **S5** Dépenses — 6 champs, engagements non débités, confirmation de débit par le trésorier

### Saisie mensuelle (M1-M6)

- **M0** Assemblée d'affaires — formulaire regroupé pour réunion, présences et PV
- **M1** Rédiger PV — auto-renseigné depuis les propositions secondées, décisions structurées
- **M2** Présences réunion d'affaires
- **M3** Rapport RSG — template 3 sections
- **M4** Envoi contributions — somme disponible affichée par défaut, destinataire + montant + méthode
- **M5** Ajuster inventaire — +/−, ajout catalogue
- **M6** Commander jetons — état stock 30 jours

### Gestion — Exécutif

- **G2** Gestion des membres — membres, invitations, droit à l'oubli
- **G9** Paramètres du groupe — nom, horaire, adresse, format
- **G11** Gestion des mandats — affecter, terminer, planifier les rotations
- **G12** Gestion des postes — créer, abolir, candidatures, accès aux modules

## Trésorerie

La source de vérité financière est le registre `transactions_comptables`.

- **Banque** et **encaisse** sont calculées depuis les écritures comptables.
- **Réserves** est calculé depuis l'historique `mouvements_reserves`.
- Toute dépense ou contribution par chèque/virement reste un engagement jusqu'à confirmation du débit.
- Les rapports mensuels doivent s'appuyer sur ce registre.

## Gouvernance

Les propositions peuvent être créées en tout temps par n'importe quel membre, sans type initial. Le cycle est : proposée → secondée → transformée en résolution par l'exécutif. Lorsqu'adoptée, la proposition devient une décision numérotée avec les préfixes `RES` (résolution), `NOM` (nomination) ou `DON` (contribution), et les sections « ÉTANT DONNÉ QUE » et « LE GROUPE A DÉCIDÉ DE ».

Le PV de la réunion d'affaires s'auto-renseigne depuis les propositions secondées en attente de vote.

## Principes

- **Anonymat AA (12e Tradition)** — prénom seul dans les écrans partagés
- **Pas d'administrateur (2e Tradition)** — permissions = exécutif du groupe
- **Mandats manuels** — aucune terminaison automatique
- **Zéro traçage** — pas d'analytics, pas de cookies tiers
- **Hébergé au Québec** — souveraineté numérique · 100 % logiciel libre

## Fichiers

```
backend/          API FastAPI (Python)
  app/
    core/         Config, DB, sécurité, rôles, règles communes
    services/     Logique métier réutilisable
    models/       Modèles SQLAlchemy
    routers/      Routes API
    schemas/      Schémas Pydantic
frontend/         React + Vite + Tailwind
  src/
    pages/        33 pages
    stores/       Zustand + API helper
    components/   Composants réutilisables
deploy/           Service systemd, NGINX, seed, backup
docs/             DEPLOIEMENT.md, RUNBOOK.md
```

## Documentation

- [Guide utilisateur](docs/UTILISATEURS.md)
- [Architecture technique](docs/ARCHITECTURE.md)
- [Déploiement Ansible](docs/ANSIBLE.md)
- [Runbook d'exploitation](docs/RUNBOOK.md)

---

*«Nos leaders sont des serviteurs de confiance ; ils ne gouvernent pas.» — 2e Tradition*