# Specification fonctionnelle - Le Juste Poids Ce document decrit la vision fonctionnelle du produit, les regles metier, les parcours utilisateurs et les contraintes comportementales du systeme. ## 1. Objectif produit Le Juste Poids est une application familiale de concours de pronostics autour de la naissance d un bebe. Le produit permet: - de gerer des comptes (admin + participants famille) - de collecter des pronostics par categorie - de definir les resultats reels - de calculer et valider les points - d annoncer les gagnants une fois le concours finalise ## 2. Personas et roles ### 2.1 Admin Responsabilites: - cree et gere les comptes utilisateurs - pilote le concours (ouverture, cloture, finalisation) - renseigne les resultats finaux - lance les suggestions automatiques de points - valide les points categorie par categorie Acces principal: - page admin: `/admin` ### 2.2 Participant famille Responsabilites: - saisit ses pronostics - consulte historique, recap et resultat final Acces principal: - espace pronostics: `/predictions` ## 3. Perimetre fonctionnel ### 3.1 Gestion des comptes - login JWT + refresh token - profil utilisateur (pseudo, photo) - role ADMIN/FAMILY - CRUD comptes reserve a ADMIN ### 3.2 Gestion des cartes de pronostics Chaque carte represente une categorie de pronostic. Attributs metier importants: - type de carte: LEGACY ou CUSTOM - type de valeur: NUMBER, TEXT, SELECT, MULTI_TEXT, DATE - champs (field) avec points, caractere requis, bornes numeriques, pas - options pour SELECT Cartes legacy pre-initialisees: - poids du bebe - sexe - prenoms - perimetre cranien - taille ### 3.3 Saisie des pronostics participants - un participant a au plus une entree par carte - mise a jour possible tant que le concours est ouvert - seules les valeurs modifiees sont envoyees et historisees - validation des champs requise cote API ### 3.4 Saisie des resultats finaux (outcomes) - faite par admin - modifiable uniquement pendant la phase OPEN - verifiee a la cloture: tous les champs requis doivent etre remplis ### 3.5 Notation et classement - suggestion automatique des points par categorie - validation manuelle par admin - calcul d un total par participant (somme des points de toutes les categories) ### 3.6 Finalisation du concours - action explicite admin - possible seulement apres notation complete - verrouille definitivement le concours - deplace la vue participant vers ecran gagnant + classement final + rappel des reponses personnelles ## 4. Machine d etat du concours Etat principal dans `PredictionGame.status`: - OPEN - CLOSED Etat fonctionnel derive: - finalized (booleen expose dans le board) Cycle de vie: 1. OPEN - pronostics autorises - outcomes autorises 2. CLOSED - pronostics interdits - outcomes interdits - scoring autorise 3. CLOSED + finalized = true - concours definitivement valide - reouverture interdite - rescoring/intervention metier interdits ## 5. Regles metier detaillees ## 5.1 Regles de saisie pronostics - refus si concours non OPEN - un champ doit appartenir a la carte cible - NUMBER exige valueNumber - DATE exige valueDate - TEXT/MULTI_TEXT/SELECT exigent valueText - SELECT doit etre dans la liste d options autorisees - les champs requis doivent etre renseignes ## 5.2 Regles de saisie outcomes - refus si concours non OPEN - les champs requis de cartes actives doivent etre renseignes pour cloturer ## 5.3 Regles de scoring auto Par champ et par participant: - NUMBER: points accordes au plus proche du resultat final - egalite de distance: ex aequo, tous obtiennent les points - TEXT/SELECT: egalite texte normalisee (trim + lowercase) - DATE: egalite stricte de date serialisee - MULTI_TEXT: correspondance normalisee sur les valeurs finales renseignees ## 5.4 Regles de validation de score - validation score autorisee uniquement en CLOSED - interdite si concours finalise - un entry note est marque isScored=true - totalPoints de l entry recalcule depuis les points valides ## 5.5 Regles de finalisation Finalisation refusee si: - concours pas CLOSED - concours deja finalise - outcomes requis manquants - aucune categorie active - aucune participation - au moins une entree non notee - classement indisponible Si OK: - activity de finalisation enregistree - finalized expose a true via le board ## 6. Parcours UX principaux ## 6.1 Parcours admin - avant cloture 1. saisit/ajuste les outcomes via tuiles 2. enregistre les outcomes 3. cloture le concours ## 6.2 Parcours admin - apres cloture 1. wizard etape par categorie 2. visualise resultat final + reponses candidats 3. ajuste/valide points pre-remplis 4. passe categorie suivante 5. recap final des totaux 6. valide definitivement le concours ## 6.3 Parcours participant Avant finalisation: - saisie pronostics + sauvegarde globale - consultation recap/historique Apres finalisation: - bloc saisie retire - ecran resultat final affiche par defaut: - gagnant(s) - classement final - vos reponses ## 7. Donnees metier principales Entites centrales: - PredictionGame - PredictionCard - PredictionCardField - PredictionEntry - PredictionEntryValue - PredictionOutcome - PredictionFieldScore - PredictionActivity Points de verite: - scores valides stockes par field score - total par entree stocke sur PredictionEntry.totalPoints - total par participant derive par aggregation de toutes ses entries ## 8. Journalisation et tracabilite - historique des saisies participant (entry history) - flux activite global (prediction activity) - evenement de finalisation marque par un message technique dedie ## 9. Permissions et securite - endpoints proteges JWT - operations admin protegees par RolesGuard - controle metier aussi dans service (pas seulement front) ## 10. API fonctionnelle de reference Participants: - GET `/predictions/cards` - GET `/predictions/board` - GET `/predictions/activity` - GET `/predictions/scoreboard` - GET `/predictions/my-entries` - PUT `/predictions/cards/:cardId/my-entry` Admin: - POST `/predictions/game/close` - POST `/predictions/game/open` - POST `/predictions/game/finalize` - POST `/predictions/cards/:cardId/outcomes` - POST `/predictions/cards/:cardId/suggest-scores` - PATCH `/predictions/entries/:entryId/scores` ## 11. Comportements attendus (acceptance) - impossible de modifier un pronostic en CLOSED - impossible de modifier outcomes en CLOSED - impossible de cloturer sans outcomes requis - impossible de finaliser si tous les participants ne sont pas notes - impossible de reouvrir apres finalisation - apres finalisation, un participant voit directement le resultat final (pas de saisie) ## 12. Limites et points d attention - la finalisation est materialisee par un evenement d activite (marker), pas par un champ dedie en base - la robustesse depend du bon maintien de ce marker dans le flux metier ## 13. Reprise de conversation Copilot Prompt recommande: "Lis d abord PROJECT_CONTEXT.md et SPEC_FONCTIONNELLE.md. Ensuite controle que les ecrans admin/famille et les regles API correspondent exactement a la spec, puis propose les ecarts et corrige-les avec build de validation."