init import projet

SPEC_FONCTIONNELLE.md

@@ -0,0 +1,277 @@
+# 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."