93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
# flashcards
|
|
|
|
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
|
|
|
|
```bash
|
|
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, http://localhost:3000) |
|
|
| `pnpm build` | Build de production + service worker (Serwist) |
|
|
| `pnpm start` | Prévisualisation du build en local |
|
|
| `pnpm test` | Tests unitaires (Vitest) |
|
|
| `pnpm test:watch` | Tests en mode watch |
|
|
| `pnpm test:coverage` | Tests + rapport de couverture (coverage/) |
|
|
| `pnpm lint` | Lint ESLint |
|
|
| `pnpm format` | Formatage Prettier |
|
|
| `pnpm typecheck` | Vérification TypeScript |
|
|
| `pnpm check` | Chaîne qualité : lint → format → typecheck → tests → coverage |
|
|
|
|
## Lancement avec Docker
|
|
|
|
```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 [docs/MOD_OP.md](docs/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
|
|
|
|
MIT — voir [LICENSE](LICENSE).
|