# 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 `theme` distinctes présentes en base (simplicité) ou gérée en entité `Theme` dé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) et `format` (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`, `test` s'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 `CardService` reposant 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 : `Theme` en table dédiée vs dérivation des `theme` distincts - [ ] 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)