mybabyguess/SPEC_FONCTIONNELLE.md

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."