docs: réécrire le README et ajouter le MOD_OP (lancement et exploitation)
This commit is contained in:
devcodetools committed
1 parent
5383f92395
commit
087945472a
2 files changed
+150
-4
No files matched your search
@@ -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`) |
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user