From 087945472af354e83b8fab97c437ace2f0312864 Mon Sep 17 00:00:00 2001 From: gilles Date: Tue, 22 Sep 2026 09:16:17 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20r=C3=A9=C3=A9crire=20le=20README=20et?= =?UTF-8?q?=20ajouter=20le=20MOD=5FOP=20(lancement=20et=20exploitation)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- MOD_OP.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 63 +++++++++++++++++++++++++++++++++++--- 2 files changed, 150 insertions(+), 4 deletions(-) create mode 100644 MOD_OP.md diff --git a/MOD_OP.md b/MOD_OP.md new file mode 100644 index 0000000..dabca39 --- /dev/null +++ b/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`) | diff --git a/README.md b/README.md index b6cf2e8..354881b 100644 --- a/README.md +++ b/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