# MyVolleyBall API

## Branches et environnements

Trois environnements, un déploiement par branche. Les mêmes règles valent pour `myvolleyball-app`.

| Environnement | Où | API | Application web | Branche | Déploiement |
|---|---|---|---|---|---|
| **localdev** | le poste de dev (Docker) | `http://localhost:8010/api` | `http://localhost:5173` | `feature/*` (ton poste) | à la main, `docker compose up` |
| **dev** (en ligne) | o2switch | `https://dapi1457.myvolleyball.org/api` | `https://dapp9714.myvolleyball.org` | **`develop`** | automatique à chaque push sur `develop` |
| **prod** (en ligne) | o2switch | `https://papi1457.myvolleyball.org/api` | `https://app.myvolleyball.org` | **`main`** | automatique à chaque push sur `main`, après validation |

| Branche | Rôle | Qui y écrit | Règle |
|---|---|---|---|
| `main` | ce qui tourne en production | **jamais à la main** : seulement par fusion de `develop` (ou de `hotfix/*`) | un push = un déploiement en prod |
| `develop` | l'environnement dev en ligne, le tronc commun ; toujours en avance sur `main` | uniquement par fusion de branches de travail (pull request) | un push = un déploiement en dev |
| `feature/<sujet>` | un chantier, créé **depuis `develop`** | toi | fusionnée dans `develop` quand elle est finie et verte |
| `fix/<sujet>` | un correctif non urgent, créé depuis `develop` | toi | comme une `feature` |
| `hotfix/<sujet>` | un correctif **urgent de production**, créé depuis `main` | toi | fusionné dans `main` **et** dans `develop` |

Quand utiliser quoi :

- **Je commence quelque chose** : `git switch develop && git pull && git switch -c feature/mon-sujet`. Je teste sur **localdev**.
- **C'est fini** : pull request vers `develop` ; la CI (`.github/workflows/ci.yml`) doit être verte. Après la fusion, **dev** se met à jour seul : c'est là qu'on teste en ligne (web, mobile « dev »).
- **Je mets en production** : pull request `develop` → `main` (jamais de commit direct sur `main`), validée dans l'environnement GitHub `prod` ; **prod** se met à jour.
- **Bug en production à corriger tout de suite** : `git switch main && git pull && git switch -c hotfix/mon-bug`, correctif, pull request vers `main`, puis fusionner `main` dans `develop` pour ne pas perdre le correctif.
- **Les deux dépôts** (`myvolleyball-api`, `myvolleyball-app`) se déploient séparément mais portent le même contrat : mettre en production l'API avant l'application qui s'en sert.

Procédure complète d'installation et de déploiement sur o2switch : `docs/deploy-o2switch.md`.

## Introduction

Utilisation de la nouvelle image docker.

### Mise en route du poste de dev (dans cet ordre)

Pas de WAMP : la base est un conteneur MySQL (dépôt voisin `myvolleyball-db`). Aucune adresse ni mot de passe n'est écrit
dans un compose : tout vient de fichiers `.env` git-ignorés, à copier depuis leur `.env.example`.

```bash
# 1. la base (crée aussi le réseau Docker partagé `myvolleyball_network`)
cd ../myvolleyball-db && cp .env.example .env && docker compose up -d
# 2. l'API : `.env` à côté de docker-compose.yml (DATABASE_URL, mêmes identifiants que la base)
cd ../myvolleyball-api && cp .env.example .env && docker compose up -d --build
# 3. dépendances, secrets de dev, schéma, jeu de données
docker exec -u 1000 -w /var/www/html -e COMPOSER_HOME=/tmp/composer myvolleyball_api composer install
docker exec -u 1000 -w /var/www/html myvolleyball_api php bin/console lexik:jwt:generate-keypair   # passphrase = JWT_PASSPHRASE
docker exec -u 1000 -w /var/www/html myvolleyball_api php bin/console app:pii:generate-key          # → PII_KEY
#    JWT_PASSPHRASE et PII_KEY vont dans app/.env.local (git-ignoré), jamais dans un fichier versionné
docker exec -u 1000 -w /var/www/html myvolleyball_api php bin/console doctrine:migrations:migrate --no-interaction
docker exec -u 1000 -w /var/www/html myvolleyball_api php bin/console doctrine:fixtures:load --no-interaction
# 4. l'app web (dépôt `myvolleyball-app`) : cp .env.example .env && docker compose up -d --build
```

Le conteneur joint la base par son nom sur le réseau Docker (`myvolleyball_db:3306`), pas par `host.docker.internal`.
Les tests utilisent `<base>_test` (créée avec la base) ; `DATABASE_URL` est le même.

## Schéma de la base

Le schéma ne se modifie **que par des migrations** (jamais `doctrine:schema:update`) :

```bash
# 1. modifier l'entité, puis générer la migration depuis la base de dev à jour
docker exec -w /var/www/html myvolleyball_api php bin/console make:migration
# 2. la relire (moteur InnoDB, index, clés étrangères), la jouer
docker exec -w /var/www/html myvolleyball_api php bin/console doctrine:migrations:migrate
```

`MigrationsTest` échoue si une entité a changé sans sa migration : il rejoue toutes les migrations sur une
base vide et compare le résultat au mapping. La migration de départ n'est jamais modifiée.

**Base de dev créée avant les migrations** (par `doctrine:schema:update`) : à marquer une seule fois comme
déjà migrée, sans la rejouer :

```bash
docker exec -w /var/www/html myvolleyball_api php bin/console doctrine:migrations:sync-metadata-storage
docker exec -w /var/www/html myvolleyball_api php bin/console doctrine:migrations:version --add --all --no-interaction
docker exec -w /var/www/html myvolleyball_api php bin/console dbal:run-sql "ALTER TABLE doctrine_migration_versions ENGINE = InnoDB"
```

(La dernière ligne : le serveur MySQL partagé crée du MyISAM par défaut ; Doctrine crée sa table de versions
sans moteur. Sur une base vide, la migration de départ s'en charge elle-même.)

Tests lents (cycle `down` puis `up` de la migration de départ, ~1 min 15) : `php bin/phpunit --group slow`.
La suite complète dure environ 3 min 30 ; le schéma de la base de test n'est reconstruit (~22 s) que si une entité a changé.


## Qualité du code

Dans le conteneur (`docker exec -w /var/www/html myvolleyball_api composer <script>`) :

| Script | Rôle |
|---|---|
| `composer cs` / `composer cs:fix` | vérifie / applique le standard `@Symfony` (PHP-CS-Fixer) |
| `composer stan` | analyse statique PHPStan, niveau 6 ; une **nouvelle** erreur échoue |
| `composer stan:baseline` | fige les erreurs actuelles dans `phpstan-baseline.neon` (à n'utiliser qu'après avoir corrigé, jamais pour cacher une nouvelle erreur) |
| `composer test` | la suite de tests (sans le groupe `slow`) |
| `composer test:coverage` | la suite avec PCOV ; échoue sous les planchers de `bin/check-coverage` (95 % des lignes au total, plus un plancher par dossier sensible : `State`, `Security`, `Tenant`, `Doctrine`, `Auth`…). Plancher à relever quand la couverture monte, jamais à baisser |
| `composer qa` | les trois ci-dessus : ce qu'un changement doit passer avant d'être commité |

**Hooks git** (lefthook, `lefthook.yml`) : pre-commit = secrets (gitleaks, image Docker épinglée) et `composer cs` ;
pre-push = `composer stan` ; commit-msg = format `type: 🐛 message` et refus de `Co-Authored-By`. À activer une fois :
installer le binaire (`npm install -g lefthook`) puis `lefthook install`. Les outils PHP tournent dans le conteneur ;
s'il est arrêté, l'étape le dit et passe. `LEFTHOOK=0 git commit …` pour passer une fois.

**Intégration continue** : `.github/workflows/ci.yml` (qualité, tests, secrets) sur chaque pull request, et avant chaque
déploiement (`.github/workflows/deploy.yml`).

PHPStan lit le conteneur de dépendances de dev (`var/cache/dev/`) : lancer une commande `bin/console`
d'abord si le cache a été vidé. Objectif : monter d'un niveau à la fois jusqu'au niveau 8, en retirant
de la baseline ce qui est corrigé.


## Versions de l'API et des applications

Une application installée sur un téléphone ne se met pas à jour en même temps que le serveur. Règles :

- **Compatible, sans nouvelle version** : ajouter un champ, un paramètre, une route, une valeur à une réponse. Une application
  ignore ce qu'elle ne connaît pas.
- **Cassant, nouvelle version majeure** : retirer ou renommer un champ, une route ou un paramètre, changer un type ou un code de
  réponse, rendre un champ obligatoire. La nouvelle version est servie sous `/api/v2` **à côté** de l'ancienne pendant six mois,
  le temps que les applications se mettent à jour.
- **`GET /api/public/meta`** (sans connexion) donne `apiVersion` (`major.minor.patch`, `app.api_version` de `config/services.yaml`)
  et `minSupportedClient` : la plus ancienne version servie pour `android`, `ios` et `web`, `null` pour aucun minimum. Une
  application plus ancienne que son minimum invite à se mettre à jour. Les minimums se règlent par les variables d'environnement
  `MIN_CLIENT_ANDROID`, `MIN_CLIENT_IOS`, `MIN_CLIENT_WEB` (à relever seulement une fois la version exclue remplacée).
- **`X-Client-Version: android/1.4.0`** : chaque application dit qui elle est dans cet en-tête. Il est seulement écrit dans les
  journaux (champ `client` de chaque ligne, jamais une décision) : quand une erreur survient, on voit quelle version l'a provoquée.
- **`tests/fixtures/openapi.contract.txt`** liste les promesses de l'API (routes, paramètres, codes de réponse, champs).
  `OpenApiContractTest` échoue à toute différence : si quelque chose a été retiré, il faut une nouvelle version majeure ; si
  quelque chose a seulement été ajouté, `UPDATE_OPENAPI_CONTRACT=1 bin/phpunit --filter OpenApiContractTest` le consigne.

## Synchroniser un appareil

Une application qui garde une copie des données (l'app mobile) rattrape le serveur par les listes, sans tout retélécharger.
Toutes ces listes acceptent `?updatedAt[after]=` : `GET /api/teams`, `/players`, `/team_members`, `/games`, `/planned_trainings`,
`/training_runs`, `/exercises`, `/training_sessions` (avec leur `scope`), `/memberships`, `/clubs/{id}/memberships` et `/clubs`.
Les listes d'un club portent `X-Club-Id`, comme toujours : un enregistrement d'un autre club n'apparaît jamais.

1. **Première fois** : lire toutes les pages de la liste (`itemsPerPage` jusqu'à 100, `page=1, 2, …` jusqu'à une page incomplète).
2. **Ensuite** : garder le plus grand `updatedAt` reçu (`M`) *une fois toutes les pages lues*, puis demander
   `?updatedAt[after]=M − 60 s` (la valeur est incluse : `>=`). Les enregistrements déjà connus reviennent : les remplacer par
   leur nouvelle version est sans effet (rejeu idempotent).
3. **Pourquoi une minute de marge** : `updatedAt` est posé à la seconde, au moment de l'écriture, et un enregistrement
   validé un peu plus tard garde sa date plus ancienne ; sans marge, il pourrait ne jamais être lu.
4. **Pages stables** : l'ordre de ces listes se termine toujours par l'identifiant (`Doctrine/StableOrderExtension`), donc deux
   enregistrements de la même seconde ne se répètent ni ne se perdent d'une page à l'autre.
5. **Économiser le transfert** : chaque lecture porte un `ETag` (hachage du corps). Rejouer la même requête avec
   `If-None-Match: <ETag>` répond **304** sans corps quand rien n'a changé ; le serveur construit quand même la réponse, ce qui
   est économisé est le transfert. Les réponses authentifiées sont `no-store` : aucun navigateur ni proxy ne renvoie l'étiquette
   de lui-même, c'est l'application qui la garde et l'envoie.
6. **Les suppressions** : un enregistrement supprimé n'est plus dans aucune liste, l'appareil ne peut pas l'apprendre par
   `updatedAt`. `GET /api/sync/deletions?since=<date>` (même marge, mêmes pages `page` / `itemsPerPage`, 500 au plus) donne
   `[{type, id, deletedAt}]`, le plus ancien d'abord, pour ce que la personne pouvait lire : les enregistrements du club de
   `X-Club-Id` (tous les membres, ou seulement le staff pour les matchs du staff et les passages d'entraînement) et sa propre bibliothèque
   (exercices, séances, matchs privés qu'elle a écrits, quel que soit le club). Jamais ceux d'un autre club.
   - `type` : `game`, `team`, `player`, `team_member`, `planned_training`, `training_run`, `exercise`, `training_session`.
   - Supprimer une équipe, un joueur ou un entraînement prévu supprime aussi, dans la base, les places dans l'équipe ou les
     passages qui en dépendent : ils sont listés eux aussi. Une équipe ou un joueur **archivé** quitte les listes : il est annoncé
     comme supprimé, avec ses places. Une fin d'adhésion annonce les places de coach de la personne.
   - Un enregistrement recréé avec le même identifiant après sa suppression a un `updatedAt` plus récent que le `deletedAt` :
     l'appareil garde l'enregistrement.
   - Les traces durent **90 jours** (`app:tokens:purge`). Un `since` plus ancien répond **410** : relire les listes en entier.
7. **Ce que cela ne dit toujours pas** : ce que la personne ne peut plus lire sans que ce soit supprimé (un exercice qui n'est plus
   partagé avec elle, un match rendu privé). Relire les listes en entier de temps en temps (par exemple à chaque ouverture après
   une semaine).

## Données de développement

Un jeu de données fictif (deux clubs, leurs comptes, équipes, joueurs, exercices, séances, passages et matchs)
se charge par :

```bash
docker exec -w /var/www/html myvolleyball_api php bin/console doctrine:fixtures:load
```

⚠️ La commande **vide d'abord toute la base de dev** (les fichiers de `var/storage/media` restent, à
effacer à la main). Les dates sont relatives au jour du chargement : on recharge pour retrouver des
séances passées et à venir. Tous les comptes ont le mot de passe `volley-dev-password` :

| Compte | Rôle |
|---|---|
| `admin@example.com` | super administrateur de la plateforme, sans club |
| `moderation@example.com` | modérateur, sans club |
| `presidente@example.com` | administratrice des Aigles de Saint-Clair |
| `thomas.girard@example.com` | entraîneur aux Aigles (seniors), administrateur du VC des Berges |
| `julie.lambert@example.com` | entraîneuse aux Aigles (M15) |
| `lea.moreau@example.com` | joueuse aux Aigles, invitée par le VC des Berges |
| `karim.haddad@example.com` | joueur au VC des Berges |
| `sans.club@example.com` | compte sans club |


## Déploiement en production

La production n'est **pas** dockerisée : l'API tourne sur un hébergement PHP classique. Rien ne doit
exiger de conteneur, de worker ni de processus permanent à côté de PHP (seulement des tâches cron).

### Prérequis du serveur

- PHP **8.4** avec les extensions `ctype`, `iconv`, `intl`, `pdo_mysql`, `gd` (avec JPEG : les
  photos sont réencodées), `sodium` (chiffrement des données personnelles), `fileinfo`, `opcache`.
- MySQL 8 en **InnoDB**, tables en `utf8mb4` / `utf8mb4_0900_ai_ci` (forcés par la configuration
  Doctrine) : toutes les écritures et les emoji. Garder `charset=utf8mb4` dans `DATABASE_URL`.
- Racine web sur `app/public`. Le serveur doit transmettre l'en-tête `Authorization` à PHP, sinon
  tout appel authentifié répond 401 « JWT Token not found ». Sous Apache :
  `SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1` (voir `image/config/apache-symfony.conf`).
- PHP-FPM de préférence : les e-mails partent après la réponse (`kernel.terminate`) ; sous mod_php
  le client attend la fin de l'envoi.

### Configuration (variables d'environnement ou coffre de secrets, jamais dans le dépôt)

| Variable | Valeur en production |
|---|---|
| `APP_ENV` | `prod` |
| `APP_SECRET` | chaîne aléatoire propre à la production |
| `DATABASE_URL` | base de production, avec `serverVersion=8.0.27` (ou la version réelle) et `charset=utf8mb4` |
| `JWT_SECRET_KEY`, `JWT_PUBLIC_KEY`, `JWT_PASSPHRASE` | paire de clés créée sur le serveur : `bin/console lexik:jwt:generate-keypair` |
| `PII_KEY` | clé de chiffrement des données personnelles : `bin/console app:pii:generate-key` |
| `MEDIA_STORAGE_DIR` | dossier des photos (chiffrées), **hors** de `public/`, inscriptible par PHP |
| `MAILER_DSN`, `MAILER_FROM` | compte SMTP ; `MAILER_FROM` doit être une adresse autorisée par ce compte (SPF/DKIM) |
| `FRONTEND_URL` | adresse publique du front (liens des e-mails) |
| `CORS_ALLOW_ORIGIN` | expression régulière des origines du front |
| `TRUSTED_PROXIES` | adresses du reverse proxy s'il y en a un. **Sans elle, derrière un proxy, tous les utilisateurs partagent l'adresse du proxy** : une seule personne qui se trompe de mot de passe use le budget de tout le monde (limites de débit par adresse) |

Les secrets peuvent aussi passer par le coffre Symfony : `bin/console secrets:set PII_KEY --env=prod`.

⚠️ **`PII_KEY` ne doit jamais changer** sur une base qui contient des données : sans elle, les dates
de naissance, contacts, licences et photos sont illisibles pour toujours. La rotation de clé n'existe
pas encore.

### Sauvegardes (ensemble, sinon elles ne servent à rien)

- la base de données ;
- le dossier `MEDIA_STORAGE_DIR` ;
- `PII_KEY` et la paire de clés JWT, conservées à part, en lieu sûr.

### Première mise en production

1. **La migration de départ existe** (`app/migrations/Version20261104101445.php`) : sur une base vide,
   `bin/console doctrine:migrations:migrate --no-interaction` construit tout le schéma (47 tables, toutes
   en InnoDB, `utf8mb4_0900_ai_ci`). Ne jamais lancer `doctrine:schema:update` en production.
2. Créer la clé `PII_KEY`, la paire de clés JWT et la configuration ci-dessus.
3. Faire le déploiement courant (ci-dessous).
4. Créer le premier administrateur de la plateforme : `bin/console app:platform-admin:create`
   (le mot de passe est demandé à l'invite, jamais en argument).
5. Vérifier l'envoi d'e-mails : `bin/console mailer:test <adresse> --from=<adresse de MAILER_FROM>`.

### Déploiement courant

Automatique : un push sur `develop` (environnement dev) ou sur `main` (prod, après validation) lance
`.github/workflows/deploy.yml` : tests, `composer install --no-dev`, puis `scripts/deploy/deploy.sh` (envoi d'une release
sur le serveur, migrations, `cache:clear`, `app:deploy:check`, **bascule du lien `current` seulement si tout est vert**).
Les cinq dernières releases restent sur le serveur : revenir en arrière = `ln -sfn releases/<ancienne> current`.
Le même script se lance à la main (voir `docs/deploy-o2switch.md`). Les deux environnements en ligne font tourner Symfony en
`APP_ENV=prod` : « dev » est une instance de test, pas le mode debug.

`app:deploy:check` sort en erreur (code 1) si le serveur a gardé quelque chose du développement : `APP_ENV` ou
debug, secret ou clé de chiffrement versionnés pour le dev et les tests, clés JWT illisibles, CORS qui accepte
`localhost`, URL du front en HTTP, mailer `null://`, mot de passe de base par défaut, dossier des médias sous
`public/` ou non inscriptible, `var/` non inscriptible, dépendances de dev installées, migrations en attente.
Un avertissement (`TRUSTED_PROXIES` vide) ne fait pas échouer. En dev elle signale des erreurs : c'est normal.

### Journaux

En production, `var/log/prod.log` (14 jours, un fichier par jour) ne contient une requête que si elle a fini en
erreur ; `var/log/deprecation.log` garde 7 jours. Aucune adresse e-mail n'y est écrite (elle est remplacée par
`[address]`). Une erreur de saisie du client (JSON invalide, IRI inconnue) n'est qu'une information, pas une erreur.

### Tâches planifiées (cron, une fois par jour)

```cron
15 3 * * * cd /chemin/vers/app && bin/console app:tokens:purge --env=prod
30 3 * * * cd /chemin/vers/app && bin/console app:deletions:purge --env=prod
*/10 * * * * cd /chemin/vers/app && bin/console app:notifications:mail --env=prod
```

Sur o2switch : `cd /home/<compte>/<dossier de l'environnement>/current/app && <PHP_BIN> bin/console …` (voir `docs/deploy-o2switch.md`).

- `app:tokens:purge` : jetons expirés, invitations expirées et notifications de plus de 90 jours.
- `app:deletions:purge` : efface définitivement les clubs et comptes dont le délai de 30 jours est
  passé (fichiers photo compris). Une exécution manquée retarde seulement l'effacement : le club ou
  le compte reste en sommeil, invisible.

### En cas de besoin

- Remettre à zéro les limites de débit : `bin/console cache:pool:clear cache.rate_limiter --env=prod`.
- Un échec d'envoi d'e-mail n'apparaît que dans les logs (`var/log/`), jamais dans la réponse.
