# 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`) |