# BEN MUSCU — plan produit et technique

## État de réalisation au 2 septembre 2026

Le socle fonctionnel principal décrit par ce document est construit dans le dépôt : PWA mobile, authentification, base Neon de 27 tables, mode autonome, coach facultatif avec commentaires, import Excel, séance persistante hors ligne, progression, récupération, nutrition, plugin ChatGPT personnel via MCP et OAuth avec état de connexion réel par utilisateur, brouillons IA à validation humaine, centre de notifications, Web Push avec historique de livraison, journaux serveur structurés sans données sportives, export personnel et suppression différée du compte.

Validations locales réalisées : compilation Next.js de production, TypeScript, ESLint, tests unitaires, schéma Neon, serveur MCP, découverte OAuth, rendu navigateur mobile et douze parcours Playwright avec scan WCAG A/AA. Ils couvrent notamment le contexte sportif de 28 jours, l’isolation sportif/coach, la création MCP et l’application après validation humaine d’un brouillon structuré, l’état ChatGPT fondé sur une autorisation réelle sans lien générique trompeur, le classeur réel, le fonctionnement hors ligne, les notifications et la suppression complète du compte.

Une Preview Vercel protégée de la nouvelle architecture compile. Restent : rendre un endpoint HTTPS accessible au scanner ChatGPT, effectuer la recette OAuth avec des comptes réels, préparer et soumettre le plugin à OpenAI, configurer l’instance Clerk Production, tester le Push sur téléphones, valider le juridique, la restauration Neon et l’observabilité, puis obtenir l’approbation explicite avant déploiement Production.

## 1. Vision du produit

Transformer le classeur Excel actuel en une application PWA mobile-first, multi-utilisateur et installable, utilisable selon deux modes :

1. **Sportif autonome** : la personne crée, planifie et exécute elle-même ses entraînements.
2. **Sportif accompagné** : la personne autorise un ou plusieurs coachs à consulter son suivi, commenter ou préparer ses programmes.

Le coach est toujours facultatif. Le sportif reste propriétaire de son espace et choisit ce qu’il partage.

Chaque utilisateur peut connecter son propre abonnement ChatGPT. L’application n’utilise pas de clé API OpenAI commune.

## 2. Ce que contient déjà l’Excel

Le classeur comporte 15 feuilles et décrit déjà une grande partie du métier :

| Domaine | Feuilles sources | Fonction à reprendre |
| --- | --- | --- |
| Tableau de bord | Accueil | Séance du jour, nutrition, cycle et progression récente |
| Exécution d’une séance | Séance du jour | Comparaison avec S-1, poids, répétitions, ressenti, RIR et commentaires |
| Programme | Lundi, Mardi, Jeudi, Vendredi, Programme V4 | Exercices, séries, objectifs, repos, consignes, substitutions et groupes musculaires |
| Périodisation | Cycle 8 semaines | Phase, intensité, progression, échec autorisé et deload |
| Progression | Historique, Records | Volume, e1RM, records, dates et commentaires |
| Morphologie | Mensurations | Poids, tour de taille, bras et autres mesures |
| Nutrition | Nutrition | Calories, protéines, dépense Garmin, balance et moyenne sur 7 jours |
| Référentiels | Listes, Vue séance V4 | Exercices, charges, répétitions, ressentis et données calculées |
| Traçabilité | Journal clôtures | Archivage des séances et clôture quotidienne |

L’import initial devra conserver l’historique existant, mais l’Excel ne deviendra pas la base de données de production.

## 3. Parcours utilisateur cible

### 3.1 Sportif autonome

1. Créer son compte.
2. Renseigner son objectif, son niveau, ses disponibilités, son matériel, ses unités et ses contraintes.
3. Importer le programme Excel ou créer un programme manuellement.
4. Planifier les séances dans un calendrier.
5. Lancer la séance du jour.
6. Saisir rapidement chaque série, même avec un réseau faible.
7. Terminer la séance et consulter le résumé, les records et les écarts par rapport au prévu.
8. Recevoir une proposition ChatGPT pour la prochaine séance.
9. Accepter, modifier ou refuser cette proposition.

### 3.2 Sportif avec coach

1. Le sportif invite un coach ou accepte son invitation.
2. Il définit les autorisations : consultation, commentaires, création de programme ou validation des propositions IA.
3. Le coach consulte son tableau de bord et ses alertes.
4. Le coach prépare ou modifie un programme sous forme de brouillon.
5. Le sportif voit clairement qui a modifié quoi et valide le changement si cette règle est activée.

### 3.3 Coach

- Liste de ses sportifs avec recherche et filtres.
- Prochaine séance, dernière activité, assiduité et alertes par sportif.
- Création de modèles de programmes réutilisables.
- Affectation d’un programme à un ou plusieurs sportifs.
- Consultation de l’historique et des progrès autorisés.
- Commentaires sur une séance et validation d’un brouillon IA.
- Aucun accès à un sportif sans invitation et consentement actifs.

## 4. Écrans principaux

### Sportif

- Accueil / aujourd’hui.
- Séance en cours.
- Calendrier et séances planifiées.
- Programmes et cycles.
- Historique.
- Records et graphiques.
- Mensurations.
- Nutrition.
- Récupération / bilan quotidien.
- Assistant ChatGPT.
- Centre de notifications.
- Profil, confidentialité et connexions.

### Coach

- Tableau de bord coach.
- Liste des sportifs.
- Fiche d’un sportif.
- Bibliothèque de programmes.
- Constructeur de programme.
- Alertes et demandes de validation.
- Invitations et autorisations.

### Administration de la plateforme

- Utilisateurs et statut des comptes.
- Signalements et incidents.
- État des notifications et tâches planifiées.
- Journal de sécurité sans contenu sportif inutile.

## 5. Séance mobile

L’écran le plus important doit être utilisable d’une seule main :

- poids et répétitions préremplis depuis le prévu ou S-1 ;
- gros boutons `−` et `+` ;
- RIR ou RPE, ressenti, douleur et commentaire facultatif ;
- substitution d’exercice sans perdre la séance prévue ;
- chronomètre de repos avec son, vibration et notification locale ;
- ajout, suppression ou duplication d’une série ;
- indication de record sans interrompre la saisie ;
- sauvegarde immédiate et mode hors connexion ;
- reprise automatique après fermeture de la PWA ;
- résumé avant clôture.

Le chronomètre entre les séries doit fonctionner localement sur le téléphone. Il ne doit pas dépendre d’une notification envoyée par le serveur.

## 6. Assistant ChatGPT personnel

### Connexion

Le parcours retenu inverse l’intégration : BEN MUSCU devient un plugin que ChatGPT appelle.

- serveur MCP HTTPS à l’adresse `/mcp` ;
- ChatGPT reste le client et utilise l’abonnement de l’utilisateur ;
- OAuth 2.1 Clerk avec PKCE et inscription dynamique du client ;
- aucun code d’appareil à recopier et aucune clé API OpenAI individuelle ;
- aucun jeton ou mot de passe ChatGPT stocké dans BEN MUSCU ;
- jeton BEN MUSCU vérifié à chaque appel MCP ;
- consentement explicite avant transmission des données sportives ;
- séparation stricte du sportif et des sportifs autorisés pour un coach.

### Contexte transmis à l’assistant

L’assistant reçoit uniquement les données utiles et autorisées :

- objectif et contraintes du sportif ;
- programme et phase du cycle en cours ;
- dernière séance équivalente ;
- quatre dernières semaines de séries réalisées ;
- charge, répétitions, RIR/RPE, volume et e1RM ;
- adhérence au programme ;
- bilan de récupération ;
- nutrition et mensurations seulement si l’utilisateur les autorise ;
- remarques du coach visibles par le sportif.

### Réponses attendues

ChatGPT peut :

- résumer la dernière séance ;
- identifier les écarts entre prévu et réalisé ;
- expliquer une stagnation observable sans inventer de cause médicale ;
- proposer les charges, répétitions, séries, repos ou substitutions de la prochaine séance ;
- proposer un deload ou une baisse de volume ;
- répondre aux questions sur l’historique du sportif.

Toute modification produite par l’IA est enregistrée comme **brouillon** avec :

- la proposition structurée ;
- les valeurs avant/après ;
- les données utilisées ;
- une justification ;
- la date et l’auteur ;
- le statut : à examiner, acceptée, modifiée, refusée ou expirée.

L’IA ne remplace jamais silencieusement une séance déjà planifiée. Le sportif ou le coach autorisé doit valider le brouillon.

## 7. Notifications

### Canaux

1. **Dans l’application** : centre de notifications permanent.
2. **Web Push PWA** : téléphone et ordinateur après consentement.
3. **E-mail** : uniquement en secours ou pour certains événements de compte, dans une phase ultérieure.

### Notifications proposées

| Événement | Destinataire | Priorité | Réglage par défaut |
| --- | --- | --- | --- |
| Séance prévue aujourd’hui | Sportif | Normale | Activé |
| Rappel avant séance | Sportif | Normale | 2 h avant, modifiable |
| Temps de repos terminé | Sportif | Immédiate et locale | Activé pendant la séance |
| Séance non commencée ou manquée | Sportif | Faible | Activé, sans culpabilisation |
| Bilan récupération à renseigner | Sportif | Normale | Matin des jours d’entraînement |
| Bilan hebdomadaire disponible | Sportif | Normale | Dimanche ou jour choisi |
| Proposition ChatGPT prête | Sportif ou coach | Normale | Activé |
| Programme modifié par le coach | Sportif | Haute | Activé |
| Commentaire du coach | Sportif | Normale | Activé |
| Sportif demande une validation | Coach | Haute | Activé |
| Inactivité inhabituelle | Sportif puis coach autorisé | Faible | Désactivé par défaut |
| Connexion ChatGPT expirée | Utilisateur concerné | Haute | Activé |
| Nouvelle connexion ou événement de sécurité | Utilisateur concerné | Haute | Toujours activé |

### Options indispensables

- consentement demandé après une action volontaire, jamais au premier écran ;
- heures silencieuses ;
- fuseau horaire par utilisateur ;
- choix des événements et des canaux ;
- heure personnalisée par jour ;
- lien profond vers la bonne séance ou demande ;
- regroupement des rappels ;
- anti-doublon et historique de livraison ;
- désabonnement et suppression des appareils expirés ;
- aucune donnée sensible détaillée dans le texte affiché sur l’écran verrouillé.

Sur iPhone, le Web Push nécessite une PWA ajoutée à l’écran d’accueil et iOS/iPadOS 16.4 ou plus récent. L’application devra détecter le support et guider l’utilisateur.

### Moteur serveur

- une file `notification_jobs` contient les notifications à envoyer ;
- une tâche planifiée sélectionne les éléments arrivés à échéance ;
- chaque envoi possède une clé d’idempotence ;
- les succès, erreurs et nouvelles tentatives sont audités ;
- le endpoint de tâche planifiée exige un secret serveur ;
- un passage toutes les 5 minutes nécessite une offre d’hébergement compatible ; sur Vercel, cela implique normalement une offre Pro ou un planificateur externe.

## 8. Options manquantes ou à confirmer

### Indispensables pour le MVP

- profil sportif : objectif, niveau, taille, poids, unités et fuseau horaire ;
- disponibilités et matériel accessible ;
- bibliothèque d’exercices et substitutions ;
- création manuelle d’un programme ;
- import initial de l’Excel ;
- mode hors connexion pendant la séance ;
- récupération : sommeil, fatigue, courbatures, stress et douleur ;
- calendrier, report et annulation d’une séance ;
- préférences de notifications ;
- export et suppression du compte ;
- consentement séparé pour le partage coach et pour les données transmises à ChatGPT ;
- journal des modifications du programme.

### Importantes après le MVP

- vidéos ou démonstrations des exercices ;
- supersets, dropsets, circuits, échauffements et séries de chauffe ;
- modèles de programmes publics ou privés ;
- messagerie coach/sportif ;
- photos de progression avec consentement séparé ;
- export PDF/CSV ;
- intégrations Garmin, Apple Health ou autres montres ;
- objectifs de pas, cardio et sommeil ;
- badges ou gamification désactivables ;
- paiements et abonnements commerciaux ;
- multi-langue et unités kg/lb.

### Décisions produit à prendre avant commercialisation

- nom définitif, identité graphique et nom de domaine ;
- public adulte uniquement ou gestion des mineurs ;
- place exacte de la nutrition : journal simple ou module complet ;
- gratuité, abonnement sportif, abonnement coach ou offre mixte ;
- règles de partage en cas de plusieurs coachs ;
- conservation des données après fin de coaching ;
- nécessité éventuelle d’un hébergement ou d’un cadre santé renforcé selon les données réellement collectées et la finalité retenue.

## 9. Protection des données et sécurité

Les données de poids, douleur, blessure, récupération ou fréquence cardiaque peuvent relever de données sensibles. Le cadrage final devra être validé juridiquement avant la mise en production.

Mesures prévues :

- minimisation des données collectées ;
- information et consentements distincts ;
- aucun stockage de session ChatGPT ;
- chiffrement des données sensibles au repos et pendant le transport ;
- autorisations strictes par sportif et par coach ;
- défense en profondeur au niveau PostgreSQL ;
- audit des accès et modifications importantes ;
- export, révocation du partage et suppression du compte ;
- rétention limitée des journaux techniques ;
- aucune donnée sportive sensible dans les logs ;
- sauvegardes chiffrées et procédure de restauration testée ;
- message clair : l’assistant ne pose pas de diagnostic médical.

## 10. Architecture proposée

### Application

- Next.js App Router en PWA mobile-first.
- Runtime Node.js pour la base, OAuth et le serveur MCP.
- Composants serveur pour les lectures principales.
- Actions serveur pour les modifications internes.
- Route Handlers pour MCP/OAuth, Web Push, import Excel, tâches planifiées et futurs connecteurs.
- Service worker pour installation, cache hors ligne et Web Push.
- IndexedDB pour la séance active et la file de synchronisation locale.

### Services

- Authentification multi-utilisateur : Clerk, comme KeepCool.
- Base PostgreSQL : Neon avec Drizzle ORM.
- Hébergement : Vercel, avec endpoint MCP HTTPS public et tâches planifiées.
- Notifications : Web Push standard avec clés VAPID.
- Assistant : plugin ChatGPT et serveur MCP `mcp-handler`, authentifiés par Clerk OAuth.
- Stockage des médias : stockage objet séparé si les photos et vidéos sont activées.

### Principales tables

- `users`, `athlete_profiles`, `coach_profiles` ;
- `coach_athlete_links`, `sharing_permissions`, `invitations` ;
- `exercises`, `exercise_variants`, `equipment` ;
- `programs`, `program_weeks`, `planned_sessions`, `planned_exercises`, `planned_sets` ;
- `session_logs`, `exercise_logs`, `set_logs` ;
- `body_measurements`, `nutrition_logs`, `wellness_checkins`, `personal_records` ;
- `assistant_conversations`, `assistant_messages` pour compatibilité des exports historiques ;
- `ai_recommendations`, `recommendation_changes`, `recommendation_reviews` ;
- `push_subscriptions`, `notification_preferences`, `notification_jobs`, `notification_deliveries` ;
- `audit_events`, `excel_imports`.

Chaque table métier doit porter l’identité du sportif propriétaire. Les lectures et écritures doivent vérifier cette propriété ainsi que les autorisations coach actives.

## 11. Phases de réalisation

### Phase 0 — Cadrage et prototype de données

- Valider le présent plan.
- Définir la marque et les choix produit encore ouverts.
- Écrire le mapping Excel vers PostgreSQL.
- Produire des wireframes mobiles des écrans critiques.
- Définir les règles de progression et les garde-fous IA.

**Validation :** chaque colonne utile de l’Excel possède une destination ou une décision d’abandon explicite.

### Phase 1 — Socle multi-utilisateur et PWA

- Créer l’application Next.js.
- Authentification et profils.
- Mode sportif autonome.
- Invitation coach facultative et permissions.
- Manifest, installation, service worker et navigation mobile.
- Schéma PostgreSQL, migrations et isolation des données.

**Validation :** deux sportifs ne peuvent jamais accéder aux données l’un de l’autre ; un sportif sans coach utilise tout le socle.

### Phase 2 — Programme et séance en cours

- Bibliothèque d’exercices.
- Créateur de programme et cycle.
- Calendrier.
- Écran de séance rapide.
- Chronomètre local.
- Mode hors ligne, reprise et synchronisation sans doublon.

**Validation :** commencer une séance en ligne, perdre le réseau, saisir plusieurs séries, fermer/réouvrir, se reconnecter et retrouver une seule version complète.

### Phase 3 — Import Excel et progression

- Import contrôlé du classeur actuel.
- Historique, records, e1RM, volume et graphiques.
- Mensurations, nutrition et récupération.
- Rapport d’import avec rejets et avertissements.

**Validation :** totaux, séances et records importés correspondent aux données sources retenues.

### Phase 4 — Coach

- Tableau de bord multi-sportifs.
- Modèles et affectation de programmes.
- Commentaires et demandes de validation.
- Alertes d’adhérence et de récupération selon consentement.
- Historique des modifications.

**Validation :** refus d’acceptation sans consentement, invitation, acceptation, consultation, permissions distinctes pour le programme et l’import des données, suspension du partage, réactivation, révocation puis impossibilité d’accès après révocation.

### Phase 5 — ChatGPT personnel

- Plugin ChatGPT relié au serveur MCP BEN MUSCU.
- OAuth Clerk en deux clics, sans code d’appareil.
- Assistant de séance et bilan hebdomadaire dans ChatGPT.
- Brouillons structurés avec comparaison avant/après.
- Validation par sportif ou coach autorisé.
- Révocation et renouvellement OAuth contrôlés.
- Avertissement visible : aucun diagnostic médical et orientation vers un professionnel qualifié en cas de douleur importante ou persistante.

**Validation :** deux utilisateurs autorisent BEN MUSCU depuis leurs propres comptes ChatGPT ; les jetons BEN MUSCU, outils et données ne se croisent jamais.

### Phase 6 — Notifications

- Centre de notifications.
- Abonnement Web Push et gestion multi-appareils.
- Préférences, heures silencieuses et fuseaux horaires.
- Tâches planifiées, reprises et audit des livraisons.
- Parcours d’installation et activation sur iPhone.

**Validation :** événement, planification, envoi, ouverture du lien profond et marquage comme lu, sans double notification.

### Phase 7 — Durcissement et mise en ligne

- Tests unitaires, intégration et navigateur mobile.
- Accessibilité et performances.
- Revue sécurité et protection des données.
- Sauvegarde/restauration.
- Observabilité sans données sensibles.
- Déploiement de préproduction, recette puis production après accord explicite.

**Validation :** parcours complet sportif autonome, parcours coach, séance hors ligne, import, ChatGPT, notification et suppression de compte.

## 12. MVP recommandé

Le premier produit réellement testable doit inclure :

- compte sportif autonome ;
- coach facultatif avec invitation ;
- import du programme et de l’historique Excel ;
- calendrier et séance mobile hors ligne ;
- historique, records et mensurations ;
- connexion ChatGPT personnelle ;
- analyse de la semaine et proposition de prochaine séance en brouillon ;
- rappels de séance et notification de brouillon prêt ;
- consentements, export et suppression du compte.

Les connecteurs Garmin/Apple Health, la messagerie, les paiements, les photos et la gamification restent hors MVP pour ne pas retarder la validation du cœur du produit.

## 13. Critère de réussite global

Un sportif doit pouvoir créer son compte sans coach, importer ou construire un programme, effectuer une semaine de séances même avec un réseau intermittent, consulter ses progrès, connecter son propre ChatGPT, recevoir une proposition argumentée pour la semaine suivante, la valider puis recevoir les rappels correspondants. Un coach invité doit pouvoir accompagner plusieurs sportifs sans jamais accéder à une donnée non autorisée.