Miss UWH — Bilan comptable d'un club de Hockey Subaquatique

PWA mobile-first qui remplace le classeur Excel de gestion comptable saisonnière d'une association sportive de Hockey Subaquatique (UWH — Under Water Hockey). Journal comptable, recettes/dépenses par catégorie, résultat par événement, clôture de saison verrouillée, justificatifs, audit, exports.

• App du club : https://mister-guiiug.github.io/miss-uwh/ (instance privée : connexion par lien e-mail, réservée aux membres créés par le club ; données hébergées sur Supabase ; installable, utilisable hors ligne après une première connexion). Pour l'essayer sans compte : npm run dev, en mode local.
• Code : https://github.com/mister-guiiug/miss-uwh
• Membre de la famille de PWA miss-* / mister-* (React 19 + Vite + Tailwind v4).

Conçu à partir d'un classeur réel (Bilan comptable 2025-2026.xlsx, club Clermont Hockey Sub) : synthèse bilan, journal Compte, 24 sous-feuilles de catégories R1–R9 / D1–D13, et l'onglet Evolution multi-saisons.

---

1. Vision produit

Donner au trésorier d'un petit club un outil aussi souple qu'un tableur mais fiable, traçable et partageable :

• saisie d'écritures en quelques secondes sur mobile, solde recalculé en temps réel ;
• bilan de saison automatique (totaux par catégorie, solde créditeur, résultat d'exploitation, trésorerie) — fini les formules cassées ;
• suivi par événement (Tournoi des Arvernes, Buvette, stages, championnat) avec résultat net ;
• clôture de saison verrouillée et report du reliquat sur la saison suivante ;
• transparence et contrôle : audit, suppression logique réversible des écritures, rôles (trésorier, président, contrôleur…) avec sécurité côté serveur ;
• migration depuis l'Excel existant (bloquée aujourd'hui par la CSP, voir § 10) et, pour l'assemblée générale, des exports CSV, Excel multi-feuilles et un bilan PDF que le trésorier partage depuis son téléphone (feuille de partage du système, téléchargement à défaut) — l'impression de l'écran reste disponible à côté.

Principe directeur : local-first dans le code (sans VITE_BACKEND, l'app tourne seule dans le navigateur, hors ligne, sans compte) et montée en sécurité via Supabase (multi-utilisateurs, RBAC serveur, MFA, audit serveur, justificatifs dans un bucket privé). L'instance publiée est en mode Supabase : .env.production, versionné, pose VITE_BACKEND=supabase pour tout build de production.

---

2. Architecture

┌──────────────────────────── Frontend (GitHub Pages, statique) ───────────────────────────┐
│  React 19 + TypeScript strict + Vite 8 + Tailwind v4 + vite-plugin-pwa (offline)          │
│                                                                                            │
│  features/        bilan · journal · categories · seasons · audit · settings · import      │
│  shared/lib/      engine.ts (moteur comptable PUR & testé) · categories · schema(zod)     │
│  store/           useAppStore (Zustand) — point unique de persistance + audit             │
│  backend/config   VITE_BACKEND = local | supabase  (switch)                               │
└───────────────┬───────────────────────────────────────────────────────────┬──────────────┘
                │ mode local (défaut)                                         │ mode supabase
        ┌───────▼─────────┐                                        ┌──────────▼───────────────┐
        │ localStorage    │                                        │ Supabase (eu-central-1)  │
        │ enveloppe       │                                        │  Postgres + RLS (RBAC)   │
        │ versionnée +    │                                        │  Auth + MFA (TOTP)       │
        │ migrations zod  │                                        │  Storage privé (PJ)      │
        └─────────────────┘                                        │  Triggers d'audit        │
                                                                   └──────────────────────────┘

• Pourquoi local-first ? GitHub Pages ne sert que du statique : une PWA locale fonctionne immédiatement, gratuitement, hors ligne, sans donnée du club qui sorte de l'appareil. Parfait pour un club mono-trésorier. L'instance publiée, elle, est en mode Supabase (voir « Ce qui sort de l'appareil », § 6).
• Pourquoi Supabase pour la sécurité ? Les exigences RBAC strict deny-by-default, MFA, audit séparé, protection des accès horizontaux/verticaux, justificatifs sécurisés et verrouillage de clôture ne peuvent pas être garanties par un bundle statique : elles exigent un serveur. Supabase (Postgres + RLS + Auth/MFA + Storage + Edge Functions) applique tout cela côté serveur. La clé anon publiée dans le bundle est inoffensive car chaque table est protégée par RLS, jamais par le client.
• Moteur comptable pur (src/shared/lib/engine.ts) : aucune dépendance UI ni réseau, testé (planchers de couverture sur le cœur pur) ; la logique métier est identique en local et en serveur.

Stack : React 19, TypeScript ~6 strict (ES2025), Vite 8, Tailwind v4 (@tailwindcss/vite), Vitest 5, vite-plugin-pwa, React Router 7 (HashRouter), Zustand, Zod 4, lucide-react, @supabase/supabase-js, @sentry/react (rapports d'erreur), posthog-js (mesure d'audience, après accord). Conventions partagées via @mister-guiiug/dev-pwa-config.

---

3. Modèle de données

Types : src/shared/types/domain.ts · Validation zod : schema.ts · Schéma SQL : supabase/migrations/0001_schema.sql.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗