docs: réécrire le README et ajouter le MOD_OP (lancement et exploitation)

MOD_OP.md

@@ -0,0 +1,91 @@
+# MOD_OP — Mode opératoire (lancement et exploitation)
+
+Procédure pas à pas pour lancer, vérifier, développer et arrêter l'application flashcards (web + MySQL + MongoDB en conteneurs Docker).
+
+## 1. Prérequis
+
+- Docker + Docker Compose installés et démarrés.
+- Node.js >= 20.19.0 et pnpm >= 9 (uniquement pour le mode dev local, étape 5).
+
+## 2. Démarrage complet (production-like)
+
+Depuis la racine du projet :
+
+```bash
+docker compose up -d --build
+```
+
+- `--build` : construit l'image du service web (nécessaire à la première exécution).
+- Le service `web` attend que `mysql` et `mongo` soient **healthy** (`depends_on` + healthchecks).
+
+Résultat attendu (3 conteneurs up) :
+
+| Service | Conteneur        | Image     | Port hôte | Port interne |
+| ------- | ---------------- | --------- | --------- | ------------ |
+| web     | flashcards-web   | (build .) | **4000**  | 3000         |
+| mysql   | flashcards-mysql | mysql:8.4 | 13306     | 3306         |
+| mongo   | flashcards-mongo | mongo:8.2 | 27018     | 27017        |
+
+> **Attention** : le port hôte 4000 a été retenu car 3000/3001 sont souvent occupés par d'autres processus. Le web écoute donc sur **http://localhost:4000**.
+
+## 3. Vérifications
+
+```bash
+docker compose ps                 # 3 services "running" (mysql/mongo "healthy")
+curl http://localhost:4000/api/themes
+curl http://localhost:4000/api/cards
+```
+
+- La liste des thèmes doit répondre `["docker","git","javascript","react","typescript"]` (seed).
+- Ouvrir **http://localhost:4000** : accueil, puis `/play` (tirage de cartes), `/cards` et `/cards/new` (CRUD).
+
+## 4. Choisir l'implémentation SGBD (`DB_IMPL`)
+
+L'application est branchée sur une couche générique : MySQL (`mysql`, défaut) ou MongoDB (`mongo`).
+
+```bash
+docker compose stop web
+DB_IMPL=mongo docker compose up -d web      # bascule sur MongoDB
+DB_IMPL=mysql docker compose up -d web      # retour sur MySQL (défaut)
+```
+
+## 5. Mode développement local (hot reload)
+
+Les bases restent en Docker, l'appli tourne en local :
+
+```bash
+cp .env.example .env
+docker compose up -d mysql mongo             # bases seules
+pnpm install
+pnpm dev                                     # http://localhost:3000
+```
+
+Le `.env` pointe vers les ports exposés des conteneurs (`localhost:13306`, `localhost:27018`) et `DB_IMPL=mysql` par défaut.
+
+## 6. Ré-initialiser le seed
+
+Les scripts `docker/init/*` ne s'exécutent **qu'à la première création des volumes** (y compris l'encodage UTF-8 forcé par `02-seed.sh`). Pour repartir d'un état vierge :
+
+```bash
+docker compose down -v     # ⚠️ supprime les données des volumes nommés
+docker compose up -d
+```
+
+## 7. Arrêt / redémarrage / nettoyage
+
+```bash
+docker compose stop        # arrêt (données conservées)
+docker compose start       # redémarrage
+docker compose restart web # redémarrage du web seul
+docker compose down        # arrêt + suppression des conteneurs (volumes conservés)
+docker compose down -v     # arrêt + suppression des conteneurs ET des volumes
+```
+
+## 8. Dépannage rapide
+
+| Symptôme                                | Action                                                                  |
+| --------------------------------------- | ----------------------------------------------------------------------- |
+| Le web ne démarre pas                   | `docker compose logs web` (il attend le healthy des bases)              |
+| `Authentication failed` (Mongo)         | Vérifier `?authSource=admin` dans `MONGODB_URI`                         |
+| Caractères accentués illisibles (MySQL) | Seed importé sans utf8mb4 → réinitialiser via l'étape 6                 |
+| Port déjà utilisé                       | Le web est sur le port hôte 4000 (modifiable dans `docker-compose.yml`) |

README.md

@@ -1,11 +1,40 @@
 # flashcards
 
-Application web PWA (Next.js 16 + React + TypeScript + Tailwind CSS 4 + Serwist).
+Application web **SPA + PWA** de cartes mémoire (flashcards) sur des sujets de code, de développement ou de culture tech. Affiche des cartes de questions/réponses et permet de gérer cette bibliothèque, avec la double persistance MySQL + MongoDB à des fins pédagogiques.
+
+## Fonctionnalités
+
+- **Jeu** : tirage d'une carte au hasard, question visible puis réponse révélée (et masquée) à la demande, tirage ciblé **par thème**.
+- **CRUD complet** : création, consultation, édition et suppression des cartes (avec confirmation).
+- **Thèmes** : liste dynamique dérivée des thèmes des cartes existantes.
+- **PWA** : installable et utilisable hors connexion (manifest + service worker Serwist).
+
+## Stack technique
+
+| Couche      | Technologie                                  |
+| ----------- | -------------------------------------------- |
+| Framework   | Next.js 16 (App Router) + React 19           |
+| Langage     | TypeScript (strict)                          |
+| Styles      | Tailwind CSS 4                               |
+| PWA         | Serwist                                      |
+| Validation  | Zod                                          |
+| SGBD        | MySQL 8.4 (mysql2) et MongoDB 8.2 (officiel) |
+| Qualité     | ESLint, Prettier                             |
+| Tests       | Vitest (unitaires + coverage)                |
+| Déploiement | Docker / docker-compose                      |
+
+## Architecture
+
+- **Couche d'accès générique** : abstraction `CardRepository` (`findAll`, `findById`, `create`, `update`, `delete`, `findRandom`, `findRandomByTheme`, `findThemes`).
+- **Deux implémentations interchangeables** : `MysqlCardRepository` et `MongoCardRepository`, sélectionnées par la variable `DB_IMPL` (`mysql` par défaut).
+- Aucun composant métier (service, route, UI) ne dépend d'un SGBD précis : il consomme uniquement l'abstraction.
+- Modèle (mock) de données unifié : `id` métier UUID commun aux deux SGBD, `question`, `response`, `theme`, `tags[]`, `createdAt`, `updatedAt`.
 
 ## Prérequis
 
 - Node.js >= 20.19.0 (ou >= 22.12.0)
 - pnpm >= 9
+- Docker + Docker Compose (pour MySQL/Mongo et le déploiement)
 
 ## Installation
 
@@ -13,11 +42,17 @@ Application web PWA (Next.js 16 + React + TypeScript + Tailwind CSS 4 + Serwist)
 pnpm install
 ```
 
+Envoyez le `.env` (voir `.env.example`) pour les variables de connexion en mode dev local :
+
+```bash
+cp .env.example .env
+```
+
 ## Commandes
 
 | Commande             | Description                                                   |
 | -------------------- | ------------------------------------------------------------- |
-| `pnpm dev`           | Serveur de développement (Turbopack)                          |
+| `pnpm dev`           | Serveur de développement (Turbopack, http://localhost:3000)   |
 | `pnpm build`         | Build de production + service worker (Serwist)                |
 | `pnpm start`         | Prévisualisation du build en local                            |
 | `pnpm test`          | Tests unitaires (Vitest)                                      |
@@ -28,9 +63,29 @@ pnpm install
 | `pnpm typecheck`     | Vérification TypeScript                                       |
 | `pnpm check`         | Chaîne qualité : lint → format → typecheck → tests → coverage |
 
-## Environnement
+## Lancement avec Docker
 
-Copiez `.env.example` vers `.env` pour définir les variables (préfixe `NEXT_PUBLIC_`).
+```bash
+docker compose up -d --build
+```
+
+Le service web est exposé sur **http://localhost:4000** avec les bases MySQL (port 13306) et MongoDB (port 27018). Le mode opératoire complet (démarrage, vérifications, dev local, arrêt, dépannage) est décrit dans [MOD_OP.md](MOD_OP.md).
+
+## Structure du projet
+
+```
+src/
+├── app/            # Routes Next.js (pages, API, manifest, service worker)
+├── components/     # Composants UI (header, vues jeu, formulaires, listes)
+├── lib/            # Client de données générique
+├── repositories/   # Implémentations MySQL et MongoDB + tests
+├── services/       # Logique métier (CardService, pagination, tirage)
+├── schemas/        # Validation Zod
+└── types/          # Types partagés
+docker/
+├── init/mysql/     # Schéma (01-schema.sql) + seed (02-seed.sh, UTF-8)
+└── init/mongo/     # Seed MongoDB (init.js)
+```
 
 ## Licence