# Installation et exploitation

Ce guide décrit l’installation locale, la mise à jour et les principaux contrôles d’exploitation de RH Connect.

## 1. Services Docker

| Service | Rôle | Persistance |
|---|---|---|
| `db` | MySQL 8 | volume `db_data` |
| `backend` | API, génération PDF/DOCX, Swagger | volume `document_templates_data` et montage paies |
| `frontend` | Interface RH Connect | aucune donnée métier locale |
| `alert-mail-scheduler` | Déclenchement planifié des alertes e-mail | historique enregistré en base |

## 2. Configuration

Créer le fichier local de configuration :

```powershell
Copy-Item .env.example .env
```

Le fichier `.env` ne doit jamais être ajouté à Git.

### Variables indispensables

| Variable | Utilisation |
|---|---|
| `MYSQL_ROOT_PASSWORD` | administration MySQL |
| `MYSQL_DATABASE` | nom de la base |
| `MYSQL_USER` / `MYSQL_PASSWORD` | compte utilisé par l’application |
| `SECRET_KEY` | signature des JWT |
| `AUTH_ADMIN_USERNAME` / `AUTH_ADMIN_PASSWORD` | compte local initial |
| `FRONTEND_ORIGIN` | origine autorisée du frontend |
| `NEXT_PUBLIC_API_URL` | adresse publique du backend vue par le navigateur |
| `PAYSLIP_HOST_PATH` | dossier hôte ou partage réseau contenant les paies |

Utiliser des valeurs longues et uniques pour les mots de passe et `SECRET_KEY`.

### Microsoft Entra ID et SSO

| Variable | Exemple ou rôle |
|---|---|
| `SSO_MODE` | `disabled` ou mode SSO configuré par l’application |
| `ENTRA_TENANT_ID` | identifiant du tenant |
| `ENTRA_CLIENT_ID` | identifiant de l’application Entra |
| `ENTRA_CLIENT_SECRET` | secret de l’application |
| `ENTRA_REDIRECT_URI` | callback backend déclaré dans Entra |
| `ENTRA_SCOPES` | généralement `openid profile email` |
| `SSO_ALLOWED_EMAIL_DOMAINS` | domaines autorisés |

L’URI de redirection configurée dans Entra doit correspondre exactement à l’adresse exposée par le backend.

### Microsoft Graph et alertes e-mail

| Variable | Utilisation |
|---|---|
| `ALERT_MAIL_FROM_EMAIL` | boîte d’expédition autorisée dans Graph |
| `ALERT_MAIL_CRON_SECRET` | protection de la route interne du planificateur |
| `ALERT_MAIL_SCHEDULE_MODE` | conserver `disabled` tant que la planification n’est pas validée |
| `ALERT_MAIL_SCHEDULE_GROUPS` | groupes destinataires planifiés |
| `ALERT_MAIL_SCHEDULE_HOUR` / `MINUTE` | heure d’exécution |
| `ALERT_MAIL_GRAPH_TEST_ENABLED` | autorise explicitement l’envoi de test |
| `ALERT_MAIL_GRAPH_TEST_RECIPIENTS` | destinataires verrouillés pour les tests |

L’application Entra doit disposer de l’autorisation Microsoft Graph nécessaire à l’envoi (`Mail.Send`) et de l’accès à la boîte utilisée.

### Fiches de paie et modèles

```dotenv
PAYSLIP_HOST_PATH=C:/chemin/paies-local
PAYSLIP_ROOT_PATH=/data/paies
DOCUMENT_TEMPLATES_ROOT=/data/document-templates
```

- `PAYSLIP_HOST_PATH` est un chemin Windows en local ou un partage monté sur le serveur ;
- `/data/paies` est monté en lecture seule dans le backend ;
- les modèles DOCX importés sont conservés dans le volume Docker `document_templates_data`.

### Swagger

```dotenv
SWAGGER_ENABLED=true
OPENAPI_SERVER_URL=http://localhost:8000
```

Conserver Swagger désactivé par défaut en production, sauf décision contraire et protection adaptée.

## 3. Premier démarrage

Vérifier que `PAYSLIP_HOST_PATH` pointe vers un dossier existant, même si celui-ci est vide en développement.

```powershell
docker compose up -d --build
docker compose exec backend npx prisma migrate deploy
docker compose restart backend
docker compose ps
```

Contrôles :

```powershell
Invoke-RestMethod http://localhost:8000/api/health
docker compose logs backend --tail=100
docker compose logs frontend --tail=100
```

Adresses locales :

- application : <http://localhost:3001> ;
- backend : <http://localhost:8000> ;
- Swagger : <http://localhost:8000/api-docs>.

## 4. Mise à jour

Avant une mise à jour :

1. sauvegarder la base ;
2. vérifier la branche et l’état Git ;
3. récupérer les changements validés ;
4. reconstruire les images ;
5. appliquer les migrations ;
6. redémarrer et exécuter les tests fonctionnels essentiels.

```powershell
git status -sb
git pull origin dev
docker compose up -d --build backend frontend
docker compose exec backend npx prisma migrate deploy
docker compose restart backend frontend
docker compose ps
```

En production, remplacer `dev` par la branche ou la référence validée par l’équipe.

## 5. Sauvegarde MySQL

Créer le dossier de sauvegarde si nécessaire :

```powershell
New-Item -ItemType Directory -Force .\backups | Out-Null
```

Sauvegarder d’abord dans le conteneur, puis copier le fichier sur l’hôte. Cette méthode évite les problèmes d’encodage liés à la redirection de Windows PowerShell 5 :

```powershell
docker compose exec -T db sh -lc 'MYSQL_PWD="$MYSQL_PASSWORD" mysqldump -u"$MYSQL_USER" --single-transaction --routines --triggers --events "$MYSQL_DATABASE" > /tmp/rh_connect_avant_migration.sql'
docker cp envie2e-db:/tmp/rh_connect_avant_migration.sql .\backups\rh_connect_avant_migration.sql
```

Vérifier que le fichier produit existe et n’est pas vide avant de poursuivre.

## 6. Persistance et suppressions

- `docker compose stop` et `docker compose down` conservent les volumes ;
- `docker compose down -v` supprime les volumes MySQL et modèles : cette commande est destructive ;
- supprimer/recréer uniquement le conteneur backend ne supprime pas les modèles DOCX ;
- les paies restent dans le dossier hôte et ne sont jamais copiées dans l’image Docker.

## 7. Diagnostic

### SSO : `OIDC callback failed fetch failed` ou `ENETUNREACH`

Tester l’accès Microsoft depuis le conteneur :

```powershell
docker compose exec backend node -e "fetch('https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration').then(r=>console.log(r.status)).catch(e=>console.error(e.cause??e))"
```

Une connexion mobile, un proxy, un VPN ou une route IPv6 indisponible peut empêcher le conteneur de joindre Microsoft.

### Graph : réponse `502`

```powershell
docker compose logs backend --tail=200 |
  Select-String -Pattern "graph|Mail.Send|token|sendMail|error" -CaseSensitive:$false
```

Contrôler la connectivité, les variables Entra, `ALERT_MAIL_FROM_EMAIL` et l’autorisation `Mail.Send`.

### Modèle DOCX introuvable (`ENOENT`)

```powershell
docker compose config |
  Select-String -Pattern "document-templates|DOCUMENT_TEMPLATES_ROOT" -CaseSensitive:$false -Context 2,3
```

Vérifier le volume `document_templates_data`. Un fichier importé avant la mise en place du volume peut devoir être réimporté.

### Fiche de paie introuvable

```powershell
docker compose exec backend sh -lc "find /data/paies -maxdepth 3 -type f | head -50"
```

Contrôler le montage, le nom du PDF et le matricule du salarié.

### Swagger non disponible

- vérifier `SWAGGER_ENABLED=true` dans `.env` ;
- reconstruire le backend ;
- ouvrir directement `/api/openapi` ;
- recharger `/api-docs` avec `Ctrl+F5`.

Swagger UI utilise des ressources distribuées par CDN : le navigateur doit disposer d’un accès Internet.

## 8. Checklist avant production

- [ ] sauvegarde MySQL vérifiée ;
- [ ] `.env` de production présent et non versionné ;
- [ ] secrets différents des valeurs locales ;
- [ ] redirect URI Entra correspondant au domaine final ;
- [ ] accès Graph et boîte expéditrice validés ;
- [ ] partage paies monté en lecture seule ;
- [ ] volumes `db_data` et `document_templates_data` persistants ;
- [ ] migrations Prisma appliquées ;
- [ ] Swagger désactivé ou protégé selon la décision d’exploitation ;
- [ ] tests SSO, habilitations, paies, documents, procédures et e-mails réalisés.