docs: add project README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
thibaud-leclere
134
README.md
Normal file
134
README.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# Actorle
|
||||
|
||||
Un jeu de devinettes inspiré de Wordle, mais autour des acteurs de cinéma. Le joueur doit deviner le nom d'un acteur lettre par lettre, en s'aidant d'indices liés aux films, personnages et récompenses des acteurs.
|
||||
|
||||
## Principe du jeu
|
||||
|
||||
1. Le joueur lance une partie. Le système choisit un acteur aléatoire (filtré par popularité TMDB).
|
||||
2. Pour chaque lettre du nom de l'acteur, un **acteur-indice** est attribué, dont le nom commence par cette lettre.
|
||||
3. Chaque ligne de la grille propose un indice sur l'acteur-indice : un **film** dans lequel il a joué, un **personnage** qu'il a incarné, ou une **récompense** qu'il a reçue.
|
||||
4. Le joueur utilise ces indices pour reconstituer le nom de l'acteur principal.
|
||||
|
||||
Les données proviennent de la filmographie Letterboxd de l'utilisateur : seuls les acteurs issus de ses films regardés sont utilisés pour générer les grilles.
|
||||
|
||||
## Stack technique
|
||||
|
||||
| Couche | Technologies |
|
||||
|------------|-----------------------------------------------------------------|
|
||||
| Backend | PHP 8.4, Symfony 8.0, Doctrine ORM, Symfony Messenger |
|
||||
| Frontend | React 19, Stimulus, Turbo, Vite 6 |
|
||||
| Base | PostgreSQL 16 |
|
||||
| Stockage | FlySystem (S3-compatible) |
|
||||
| Serveur | FrankenPHP (dev), Caddy (prod) |
|
||||
| Infra | Docker Compose |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── Controller/ # Contrôleurs (Game, Import, Auth)
|
||||
├── Entity/ # Entités Doctrine (Game, Actor, Movie, Award...)
|
||||
├── Service/ # Logique métier (GameGridGenerator, FilmImporter, ActorSyncer, AwardImporter)
|
||||
├── Repository/ # Requêtes Doctrine
|
||||
├── Gateway/ # Intégrations externes (TMDB, Wikidata, Letterboxd)
|
||||
├── Message/ # Messages async (ProcessImport, ImportFilmsBatch)
|
||||
├── MessageHandler/ # Handlers Symfony Messenger
|
||||
├── EventListener/ # Abandon auto des parties anonymes au login
|
||||
├── Form/ # Formulaires (inscription)
|
||||
└── Model/ # DTOs (TMDB, Letterboxd)
|
||||
```
|
||||
|
||||
## Intégrations externes
|
||||
|
||||
- **TMDB API** : recherche de films, récupération des castings et crédits
|
||||
- **Wikidata SPARQL** : récupération des récompenses des acteurs (Oscars, BAFTA, etc.)
|
||||
- **Letterboxd** : import de la filmographie via export CSV
|
||||
|
||||
## Import de films
|
||||
|
||||
1. L'utilisateur exporte son historique depuis Letterboxd (CSV).
|
||||
2. Il upload le fichier via l'interface.
|
||||
3. Un message async découpe l'import en **batchs de 50 films**.
|
||||
4. Chaque batch recherche les films sur TMDB, synchronise les acteurs et importe leurs récompenses depuis Wikidata.
|
||||
5. L'avancement est consultable en temps réel via l'API (`GET /api/imports/latest`).
|
||||
|
||||
## Installation
|
||||
|
||||
### Prérequis
|
||||
|
||||
- Docker et Docker Compose
|
||||
- Un token API TMDB
|
||||
|
||||
### Lancement en développement
|
||||
|
||||
```bash
|
||||
# Démarrer les conteneurs (app, messenger, database, node)
|
||||
make dev:up
|
||||
|
||||
# Installer les dépendances npm
|
||||
make node:install
|
||||
|
||||
# Exécuter les migrations
|
||||
make db:migrate
|
||||
```
|
||||
|
||||
L'application est accessible sur `http://localhost`.
|
||||
Le serveur Vite (HMR) tourne sur le port `5173`.
|
||||
|
||||
### Configuration
|
||||
|
||||
Les secrets (token TMDB, etc.) se gèrent via Symfony Secrets :
|
||||
|
||||
```bash
|
||||
make symfony:secrets-set NAME="TMDB_API_TOKEN"
|
||||
```
|
||||
|
||||
Variables d'environnement principales :
|
||||
|
||||
| Variable | Description |
|
||||
|---------------------------|------------------------------------|
|
||||
| `APP_ENV` | Environnement (`dev` / `prod`) |
|
||||
| `APP_SECRET` | Secret Symfony |
|
||||
| `TMDB_API_TOKEN` | Token API TMDB (via secrets) |
|
||||
| `POSTGRES_HOST` | Hôte PostgreSQL |
|
||||
| `POSTGRES_USER` | Utilisateur PostgreSQL |
|
||||
| `POSTGRES_PASSWORD` | Mot de passe PostgreSQL |
|
||||
| `POSTGRES_DB` | Nom de la base |
|
||||
| `MESSENGER_TRANSPORT_DSN` | DSN du transport Messenger |
|
||||
|
||||
## Commandes utiles
|
||||
|
||||
```bash
|
||||
make dev:up # Démarrer le dev
|
||||
make dev:down # Arrêter le dev
|
||||
make dev:logs # Logs en temps réel
|
||||
make dev:shell # Shell dans le conteneur app
|
||||
make db:migrate # Exécuter les migrations
|
||||
make db:migration # Générer une migration
|
||||
make db:reset # Reset complet de la base
|
||||
make test # Lancer les tests PHPUnit
|
||||
make node:build # Build des assets pour la prod
|
||||
make help # Afficher toutes les commandes
|
||||
```
|
||||
|
||||
## Déploiement
|
||||
|
||||
```bash
|
||||
# Build et push des images vers le registry
|
||||
make docker:build
|
||||
make docker:push
|
||||
|
||||
# Sur le serveur de production
|
||||
make prod:up
|
||||
```
|
||||
|
||||
Les images sont hébergées sur le registry Gitea `git.lclr.dev`.
|
||||
|
||||
## Services Docker
|
||||
|
||||
| Service | Description |
|
||||
|-------------|-----------------------------------------------------|
|
||||
| `app` | Application FrankenPHP (dev) / Caddy (prod) |
|
||||
| `messenger` | Worker Symfony Messenger (consomme la queue `async`) |
|
||||
| `database` | PostgreSQL 16 |
|
||||
| `node` | Vite dev server avec HMR (dev uniquement) |
|
||||
Reference in New Issue
Block a user