Merge branch 'develop' into feature/LST-72-amelioration-frontend-de-la-partie-repertoire

2026-06-27 11:05:59 +00:00
parent eef4bbac1c 0ee164c302
commit e0c530d93a
41 changed files with 2616 additions and 166 deletions
@@ -23,6 +23,7 @@ Application de gestion de projet avec suivi du temps et portail client.
 - Intégration Gitea (issues, repos)
 - Intégration Mail IMAP (boîte partagée OVH, voir `docs/mail-integration.md`)
 - Serveur MCP pour assistants IA
+- Error tracking centralisé back + front (GlitchTip / SDK Sentry, prod uniquement — voir « Error tracking »)
 - Multi-langue (i18n)

 ## Prérequis
@@ -74,6 +75,7 @@ peuvent être surchargées dans `.env.local` (jamais committé). En prod, elles
 | `CORS_ALLOW_ORIGIN` | Origines CORS autorisées | localhost | ✅ (domaine prod) |
 | **`ENCRYPTION_KEY`** | **Clé hex 32 bytes chiffrant les credentials IMAP/SMTP (feature mail)** | placeholder | ✅ — doit rester **stable**, sinon les credentials mail stockés deviennent illisibles |
 | **`LOCK_DSN`** | **Store de verrous Symfony pour la sync mail (anti-chevauchement)** | `flock` | `flock` suffit |
+| `SENTRY_DSN` | Error tracking **backend** → GlitchTip (projet `lesstime-api`) | _(vide)_ | ⚪ optionnel — active le tracking (voir « Error tracking ») |

 > **Messagerie** : `ENCRYPTION_KEY` et `LOCK_DSN` sont introduites par l'intégration mail.
 > Détails de config et cron de synchronisation : `docs/mail-integration.md` et `docs/mail-cron-setup.md`.
@@ -217,28 +219,60 @@ Lesstime expose un serveur MCP (Model Context Protocol) permettant aux assistant
 }
 ```

-### Configuration réseau (HTTP)
+### Configuration réseau (HTTP) — par poste, hors git
+
+Le transport HTTP nécessite un **token API** (Bearer), qui est un **secret** : il ne va **jamais**
+dans le `.mcp.json` versionné (celui-ci ne contient que le serveur STDIO local, sans secret).
+Chaque développeur configure le serveur HTTP dans sa **config Claude Code locale**.
+
+**Méthode recommandée (identique sur Fedora, Windows et macOS) :**
+
+```bash
+claude mcp add --transport http --scope user lesstime \
+  http://project.malio-dev.fr/_mcp \
+  --header "Authorization: Bearer <api-token>"
+```
+- En prod : `http://project.malio-dev.fr/_mcp`
+- En réseau local : `http://<ip-serveur>:8082/_mcp`
+
+**Où c'est stocké** (si tu édites le fichier à la main, sous la clé `mcpServers`) :
+
+| OS | Fichier de config Claude Code |
+|----|-------------------------------|
+| **Fedora / Linux** | `~/.claude.json` |
+| **Windows** (collègue) | `%USERPROFILE%\.claude.json` (ex. `C:\Users\<user>\.claude.json`) |
+| **macOS** | `~/.claude.json` |

 ```json
 {
  "mcpServers": {
    "lesstime": {
-      "type": "url",
-      "url": "http://<ip-serveur>:8082/_mcp",
-      "headers": {
-        "Authorization": "Bearer <api-token>"
-      }
+      "type": "http",
+      "url": "http://project.malio-dev.fr/_mcp",
+      "headers": { "Authorization": "Bearer <api-token>" }
    }
  }
 }
 ```

+Après modification, relancer la connexion avec `/mcp` dans Claude Code.
+
 ### Gestion des tokens API

+Générer / régénérer un token pour un utilisateur :
+
 ```bash
+# En dev (container local)
 docker exec -u www-data php-lesstime-fpm php bin/console app:generate-api-token <username>
+
+# En prod (sur le serveur, dans infra/prod)
+sudo docker compose exec -T -u www-data app php bin/console app:generate-api-token <username>
 ```

+⚠️ Le token est **invalidé à chaque reset/reseed de la base**. Symptôme : `/mcp` renvoie
+`HTTP 401 "Invalid API token"`. Il faut alors le **régénérer** (commande ci-dessus) puis remplacer
+la valeur `Bearer ...` dans ta config locale (par poste).
+
 ## Déploiement

 La prod tourne en **Docker** : l'image est buildée par la CI Gitea sur push de tag `v*`
@@ -255,6 +289,131 @@ Le script active la maintenance, pull l'image, redémarre le container, lance le
 et vide le cache. Guide complet (première installation, BDD, Nginx, JWT, rollback) :
 **`doc/deployment-docker.md`**.

+## Error tracking (GlitchTip)
+
+Les erreurs **backend** et **frontend** sont remontées vers **GlitchTip** (instance auto-hébergée
+interne, compatible SDK Sentry) qui les **groupe par projet** et compte les occurrences. Activé
+**uniquement en prod** : en dev, sans DSN, le SDK est inerte (zéro impact). Ticket de référence :
+INFRA #146.
+
+### Pourquoi back et front se configurent différemment
+
+| | Backend (Symfony) | Frontend (Nuxt SPA) |
+|---|---|---|
+| Nature | process PHP qui tourne en continu | fichiers JS/HTML **statiques** (`nuxt generate`) |
+| Quand le DSN est lu | au **runtime** | **figé au build** (baké dans le JS) |
+| Où mettre le DSN | `.env` du serveur (`/var/www/lesstime/.env`) — runtime | **secrets Gitea** → build-args de la CI |
+
+> Les erreurs partent **toujours vers GlitchTip**, jamais vers la CI. La CI ne sert qu'à *écrire*
+> le DSN front dans le bundle au moment du build (il n'y a aucun process front en prod qui
+> pourrait lire une variable d'environnement).
+
+### Variables
+
+**Backend — fichier `.env` du serveur** (`/var/www/lesstime/.env`, chargé via `env_file` ; le repo ne fournit que le template `infra/prod/.env.example`) :
+```env
+SENTRY_DSN=http://<clé>@glitchtip.interne:<port>/<id-projet-api>
+```
+
+**Frontend — secrets Gitea** (repo → Settings → Actions → Secrets), consommés par
+`.gitea/workflows/build-docker.yml` :
+
+| Secret Gitea | Rôle |
+|---|---|
+| `SENTRY_FRONT_DSN` | DSN du projet `lesstime-front` (public, baké dans le JS) |
+| `SENTRY_URL` | URL de l'instance GlitchTip |
+| `SENTRY_ORG` | slug de l'organisation GlitchTip |
+| `SENTRY_FRONT_PROJECT` | slug du projet front |
+| `SENTRY_AUTH_TOKEN` | token d'upload des **source maps** (vrai secret) |
+
+> Sans source maps, seul `SENTRY_FRONT_DSN` est requis (les stacktraces front seront sur du JS
+> minifié). Le build n'échoue pas si les autres secrets sont absents.
+
+### Fichiers concernés
+
+| Fichier | Rôle |
+|---|---|
+| `config/packages/sentry.yaml` | conf backend (prod-only, exceptions, 4xx ignorés, release = `app.version`) |
+| `config/bundles.php` | `SentryBundle` enregistré `['prod' => true]` |
+| `frontend/nuxt.config.ts` | module Sentry chargé **uniquement si DSN présent** + upload source maps |
+| `frontend/sentry.client.config.ts` | init du SDK client (no-op si DSN vide) |
+| `infra/prod/Dockerfile` | build-args front (`NUXT_PUBLIC_SENTRY_DSN`, `SENTRY_*`) |
+| `.gitea/workflows/build-docker.yml` | injection des secrets Gitea en build-args |
+
+### Activation (résumé)
+
+1. Dans GlitchTip : créer les projets `lesstime-api` et `lesstime-front`, récupérer les 2 DSN
+   (+ un auth token pour les source maps).
+2. Backend : ajouter `SENTRY_DSN` dans le `.env` du serveur (`/var/www/lesstime/.env`).
+3. Frontend : ajouter les secrets Gitea ci-dessus.
+4. Tagger une version (`v*`) → la CI build l'image avec le DSN front baké → `deploy.sh`.
+
+### Certificat HTTPS interne (CA auto-signée)
+
+GlitchTip est servi en **HTTPS** sur `https://logs.malio-dev.fr` (nginx devant), avec un certificat
+**auto-signé** par une **CA interne** (« MALIO-DEV Local Root CA », cert serveur `*.malio-dev.fr`).
+`malio-dev.fr` est un **domaine interne uniquement** (DNS local, pas de résolution publique).
+
+> **Pourquoi pas Let's Encrypt ?** Une CA publique doit valider le domaine via Internet (challenge
+> HTTP ou DNS public). Comme `malio-dev.fr` n'existe qu'en interne, aucune validation n'est
+> possible → on reste sur la CA interne, qu'il faut faire **approuver partout** où la connexion TLS
+> est établie. Tant que la CA n'est pas approuvée, **rien ne remonte** : le backend logue
+> « Message not sent » (SDK Sentry) et le navigateur affiche « connexion non sécurisée » (le front
+> n'envoie rien).
+
+**Qui doit faire confiance à la CA ?** La connexion à `logs.malio-dev.fr` part de deux endroits
+différents, donc deux fixes distincts :
+
+| Émetteur des erreurs | Qui établit le TLS | Où approuver la CA |
+|---|---|---|
+| Backend (Symfony) | le **container PHP** | CA bakée dans l'**image Docker** (ci-dessous) |
+| Frontend (SPA) | le **navigateur du poste** | CA poussée sur les **postes via GPO** (ci-dessous) |
+
+#### Fix backend — CA bakée dans l'image
+
+Le certificat **public** de la root CA est committé dans le repo (`infra/prod/malio-dev-root-ca.crt`,
+aucune clé privée) et installé dans le trust store du container au build (`infra/prod/Dockerfile`,
+stage production — `ca-certificates` est déjà installé) :
+
+```dockerfile
+COPY infra/prod/malio-dev-root-ca.crt /usr/local/share/ca-certificates/malio-dev-root-ca.crt
+RUN update-ca-certificates
+```
+
+Le container fait alors confiance à tout `*.malio-dev.fr` interne et le SDK Sentry backend peut
+envoyer. Vérification :
+
+```bash
+curl --cacert infra/prod/malio-dev-root-ca.crt https://logs.malio-dev.fr/api/1/store/   # → HTTP 200
+```
+
+#### Fix postes — CA poussée par GPO (Active Directory)
+
+Le front est une SPA : c'est le **navigateur de l'utilisateur** qui contacte `logs.malio-dev.fr`,
+donc c'est le **poste** qui doit faire confiance à la CA (la CA de l'image ne sert qu'au backend).
+Sur le domaine Active Directory, on pousse la CA **une seule fois via GPO** plutôt que poste par poste :
+
+1. Contrôleur de domaine → **Group Policy Management** → éditer une GPO.
+2. `Configuration ordinateur → Stratégies → Paramètres Windows → Paramètres de sécurité → Stratégies
+   de clé publique → Autorités de certification racines de confiance`.
+3. Clic droit → **Importer** → sélectionner `rootCA.crt` (« MALIO-DEV Local Root CA »).
+4. Sur les postes : `gpupdate /force` (ou attendre le rafraîchissement), puis **redémarrer le navigateur**.
+
+- Chrome / Edge utilisent le magasin Windows → confiance automatique.
+- ⚠️ **Firefox** a son propre magasin : activer `security.enterprise_roots.enabled = true`
+  (`about:config` ou via policy) pour qu'il lise le magasin Windows.
+
+> **Validation poste** : ouvrir `https://logs.malio-dev.fr` → cadenas vert sans avertissement = CA
+> approuvée = le front peut envoyer.
+
+#### Renouvellement / changement de CA
+
+Si la CA interne change (rotation, expiration) :
+
+1. Remplacer `infra/prod/malio-dev-root-ca.crt` par le nouveau certificat public, commit + **rebuild
+   de l'image** (re-tag `v*`) pour le backend.
+2. **Re-pousser** la nouvelle CA via GPO (étapes ci-dessus) pour les postes.
+
 ## Licence

 Propriétaire — Tous droits réservés.