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