9.5 KiB
9.5 KiB
TODO — Application web Flashcards (développement assisté par IA)
Document de spécifications et checklist destiné à guider un agent IA dans le développement complet de l'application. Il complète le GOAL.md en le rendant actionnable.
1. Contexte produit
Application web SPA + PWA : Flashcards affiche des cartes (questions/réponses) sur des sujets de code, de développement ou de culture tech.
Principe du jeu
- Affichage d'une carte au hasard : une question ou un terme apparaît, la réponse est cachée.
- L'utilisateur peut révéler la réponse à la demande.
- Possibilité de tirer une carte au hasard sur un thème précis (code, langage, etc.).
Gestion des cartes
- L'utilisateur peut créer, modifier ou supprimer une carte (CRUD complet).
- L'utilisateur peut afficher la liste des cartes ou consulter une carte spécifique.
2. Exigences fonctionnelles
Chaque exigence doit être satisfaite avant de considérer la feature terminée.
| Ref | Exigence | Critère d'acceptation |
|---|---|---|
| F-01 | Afficher une carte au hasard | Un clic sur « Jouer » affiche UNE carte tirée aléatoirement de l'ensemble des cartes |
| F-02 | Dans un tirage aléatoire, la question est visible et la réponse cachée | Le terme/question s'affiche ; la réponse ne s'affiche pas |
| F-03 | Révéler la réponse | Un clic (ou action) déroule/affiche la réponse cachée ; un second clic la masque |
| F-04 | Tirer une carte au hasard par thème | L'utilisateur choisit un thème ; le tirage se fait uniquement parmi les cartes de ce thème |
| F-05 | Créer une carte | Formulaire de création avec question, réponse et thème ; la carte est persistée |
| F-06 | Modifier une carte | Formulaire pré-rempli ; la modification est persistée |
| F-07 | Supprimer une carte | Confirmation avant suppression ; la carte disparaît de la liste |
| F-08 | Lister les cartes | La liste complète des cartes s'affiche (avec au minimum question + thème) |
| F-09 | Consulter une carte spécifique | L'accès direct à une carte (via sa route/id) affiche son détail complet |
| F-10 | Thèmes | L'utilisateur peut choisir un thème reflétant les cartes existantes |
3. Modélisation de données (proposition à valider)
Entité Card
| Champ | Type | Contrainte | Description |
|---|---|---|---|
id |
string/INT | unique (PK) | Identifiant stable de la carte |
question |
string | requis | Terme ou question affiché |
response |
string | requis | Réponse cachée puis révélée |
theme |
string | requis | Thème/catégorie (ex. « code », « javascript ») |
tags |
string[] | optionnel | Mots-clés additionnels |
createdAt |
datetime | auto | Date de création |
updatedAt |
datetime | auto | Date de dernière modification |
La liste des thèmes peut être dérivée dynamiquement des valeurs
themedistinctes présentes en base (simplicité) ou gérée en entitéThemedédiée (robustesse). Choix à figer en phase de conception.
Représentation duale SGBD
- MySQL : table
cards - MongoDB : collection
cards
Le même id doit permettre de retrouver une carte dans les deux SGBD (l'id métier n'est pas nécessairement l'id technique Mongo).
4. Exigences techniques et architecture
Stack
- Framework : Next.js
- Langage : TypeScript (strict)
- Styles : Tailwind
- Qualité : ESLint, Prettier
- Tests unitaires : Vitest avec coverage
Base de données — double SGBD simultané (contrainte pédagogique)
Bien qu'il n'y ait pas réellement besoin de 2 SGBD, dans un but pédagogique les deux bases doivent être gérées simultanément :
- MySQL (conteneur Docker)
- MongoDB (conteneur Docker)
Exigence architecturale majeure : couche d'accès aux données GÉNÉRIQUE
Les composants d'accès aux données doivent être le plus générique possible. Concrètement :
- Définir une abstraction commune (interface/repository générique, ex.
CardRepository) exposant les opérations :findAll,findById,create,update,delete,findRandom,findRandomByTheme,findThemes. - Fournir deux implémentations de cette abstraction : une pour MySQL, une pour MongoDB.
- Aucun composant métier (service, route, UI) ne doit dépendre d'un SGBD précis : il consomme uniquement l'abstraction.
- Les deux implémentations doivent être utilisables et activables (par config/DI/injection), et les tests doivent couvrir les deux.
Déploiement
- Docker via docker-compose
- Volumes nommés pour la persistance des données des 2 SGBD
- Services au minimum :
web(Next.js),mysql,mongo
5. Définition de fait (Definition of Done)
Une feature est « faite » si et seulement si :
- Les tests unitaires (Vitest) passent, coverage généré et au-dessus du seuil défini
lint(ESLint) etformat(Prettier — check) sans erreur- TypeScript strict compile sans erreur
- L'implémentation est branchée sur la couche générique d'accès aux données
- Les deux SGBD (MySQL + MongoDB) fonctionnent simultanément en local
- Le comportement correspond aux critères d'acceptation de la section 2
- Construit et lançable via docker-compose avec volumes persistants
6. Checklist de développement par phases
Ordre d'exécution recommandé. Passer à la phase suivante uniquement si la DoD de la phase courante est remplie.
Phase 0 — Scaffolding
- Initialiser le projet Next.js + TypeScript (strict)
- Configurer Tailwind
- Configurer ESLint + Prettier
- Configurer Vitest + rapport de coverage
- Fixer le seuil de coverage (à définir, ex. 80%)
- DoD :
lint,format,typecheck,tests'exécutent sans erreur sur un squelette
Phase 1 — Données et couche d'accès générique
- Schéma MySQL (table
cards) + migration/seed - Schéma MongoDB (collection
cards) + seed - Interface générique
CardRepository(contrat complet) - Implémentation
MysqlCardRepository - Implémentation
MongoCardRepository - Mécanisme d'activation/sélection de l'implémentation (config)
- Tests unitaires des deux implémentations
- DoD : phase 0 + les 2 repositories testés et interchangeables
Phase 2 — API / services métier
- Service métier
CardServicereposant uniquement sur l'abstraction repository - Routes API : liste, détail, création, modification, suppression
- Routes API : tirage aléatoire simple + tirage aléatoire par thème + liste des thèmes
- Validation des entrées (contrats TypeScript / schémas)
- Gestion d'erreurs cohérente (404 carte inconnue, 400 payload invalide…)
- Tests unitaires du service (mock du repository)
- DoD : phases précédentes + contexte de MCP de l'API
Phase 3 — Interface utilisateur
- Page/vue liste des cartes (F-08)
- Page/vue détail d'une carte (F-09)
- Formulaire création (F-05)
- Formulaire édition (F-06)
- Suppression avec confirmation (F-07)
- Vue jeu : tirage aléatoire global + sélecteur de thème (F-01, F-02, F-03, F-04, F-10)
- Navigation/flux SPA cohérent (routes Next.js)
- DoD : phases précédentes + parcours utilisateur complet fonctionnel
Phase 4 — Tests
- Tests des composants UI (composants critiques)
- Couverture des critères F-01 à F-10
- Coverage au seuil défini (Phase 0)
- DoD : toutes phases précédentes vertes + coverage ok
Phase 5 — PWA, déploiement
- Manifest PWA + service worker (installable, hors-ligne) — la stack SPA le permet
docker-compose.yml:web,mysql,mongo- Volumes nommés pour l'ensemble des données
- Variables/env de connexion aux 2 SGBD selon l'implémentation sélectionnée
- Construction de l'image web et démarrage complet via
docker compose up - Test de persistance après redémarrage des conteneurs
- DoD finale pleinement vérifiée
7. Points à trancher / en attente de décision
- Couverture : seuil de coverage exact
- Selon cas :
Themeen table dédiée vs dérivation desthemedistincts - Choix par défaut de l'implémentation repository pour la prod (MySQL ou Mongo)
- Authentification éventuelle (hors périmètre README, à confirmer si nécessaire)