# Troubleshooting — pièges connus de l'environnement de dev

Ce document recense les **problèmes récurrents** rencontrés sur l'environnement de développement local de VIIZIA et leur correctif. Si vous ne voyez pas votre symptôme ici, créez une nouvelle entrée après l'avoir résolu.

## Sommaire

- [PDF LCL compte courant (débit / crédit)](#pdf--relev-lcl-compte-courant-dbit--crtit)
- [Bind mounts Docker Desktop Mac qui se désynchronisent](#bind-mounts-docker-desktop-mac-qui-se-désynchronisent)

---

## PDF — relevé LCL compte courant (DÉBIT / CRÉDIT) {#pdf--relev-lcl-compte-courant-dbit--crtit}

### Symptôme

À l’import d’un PDF « compte courant » LCL, les mouvements de la colonne **DÉBIT** sont listés comme des **entrées** au lieu de **sorties**.

### Cause probable

Une extraction qui **fusionne ou casse les colonnes** ne conserve pas deux zones alignées : sans indication de colonne ou de signe clair, un montant sans signe explicite est interprété comme crédit (entrée).

### À faire sur la machine / le conteneur

- **Sans Docker sur le Mac** : `brew install poppler`. Si Symfony tourne hors container mais que php-fpm a un PATH minimal, utilisez **`PDFTOTEXT_BINARY=/opt/homebrew/bin/pdftotext`** (Apple Silicon) ou **`/usr/local/bin/pdftotext`** (Intel).
- **Avec Docker (projet VIIZIA)** : `brew install` sur l’**hôte** ne rend pas `pdftotext` disponible **dans le conteneur** `viizia-php`. L’image doit inclure `poppler-utils` (voir `docker/php/Dockerfile`) puis : **`docker compose build --no-cache viizia-php`** et redémarrer les services.


### Débogage précis

Définir **`PDF_IMPORT_DIAG=1`** (fichier d’env du projet ou serveur) ; consulter **`var/log/pdf_import_diag.log`** après une tentative de préparation d’import. En cas d’échec `pdftotext`, le journal liste les **binaires effectivement utilisés comme candidats**.

### Pré-visualisation qui ne change pas après une correction de code

Si le job conserve déjà des lignes `pdf_review`, **`preparePreviewIfNeeded` ne refait pas l’analyse**. Réinitialisez le job d’import (flux « réessayer après échec » prévu dans l’app) ou supprimez le bloc `pdf_review` du mapping pour forcer une nouvelle extraction.

## Bind mounts Docker Desktop Mac qui se désynchronisent

### Symptôme

Vous modifiez un fichier (par exemple `public/css/app.css`, un template Twig, ou un Dockerfile) et **rien ne change** dans le navigateur, même après un hard-refresh (`Cmd + Shift + R`). Le serveur semble servir une version obsolète.

Indices typiques :

- Un fichier modifié côté hôte n'apparaît pas dans le container.
- Une nouvelle classe CSS ne fonctionne pas alors que le fichier la contient bien sur votre Mac.
- Un fichier de config (`docker/nginx/default.conf`) modifié n'est pas pris en compte au reload.

### Cause

**Bug connu de Docker Desktop pour Mac** : les bind mounts de répertoires (`./public:/var/www/html/public`, etc.) peuvent se désynchroniser silencieusement après certaines opérations :

- Modification de `compose.yaml`
- Rebuild d'image (`docker compose build`)
- Mise en veille / sortie de veille du Mac
- Restart de Docker Desktop
- Mise à jour de Docker Desktop

Le container continue de tourner mais voit un dossier vide (ou figé dans un état antérieur) à la place du dossier monté.

### Diagnostic

Comparez le contenu vu côté hôte et côté container :

```bash
# Cote hote
ls -la public/

# Cote container nginx
docker compose exec viizia-nginx ls -la /var/www/html/public/

# Cote container php
docker compose exec viizia-php ls -la /var/www/html/public/
```

Si **l'un des containers retourne un dossier vide** ou des fichiers obsolètes alors qu'ils existent côté hôte, c'est un bind mount désynchronisé.

Vérification supplémentaire — le bind mount est-il toujours déclaré ?

```bash
docker inspect viizia-nginx --format '{{range .Mounts}}{{println .Type "->" .Source "->" .Destination}}{{end}}'
```

Vous devriez voir une ligne du type :

```
bind -> /Users/.../neoloop-viizia/public -> /var/www/html/public
```

Si la ligne est présente mais que `ls` retourne vide → bind mount cassé, fix ci-dessous.

### Fix

Redémarrer le service concerné (**pas besoin** de `down/up` complet) :

```bash
docker compose restart viizia-nginx
```

Ou pour le service PHP si c'est lui qui est touché :

```bash
docker compose restart viizia-php
```

Vérifiez ensuite que le contenu réapparaît :

```bash
docker compose exec viizia-nginx ls -la /var/www/html/public/
```

Puis dans votre navigateur, faites un **hard refresh** (`Cmd + Shift + R`) car le navigateur peut avoir mis en cache l'ancienne version des fichiers statiques.

### Prévention

- Si vous reprenez votre Mac après une mise en veille longue → un `docker compose ps` rapide ne suffit pas, faites un test en lisant un fichier critique côté container avant de chercher l'erreur ailleurs.
- Après un changement de `compose.yaml`, faire systématiquement `docker compose up -d` (qui détecte et recrée les containers concernés) plutôt qu'un simple `restart`.
- Si le problème devient récurrent, envisager `docker compose down && docker compose up -d --build` pour repartir au propre. **Attention** : `down -v` supprimerait les volumes nommés (`viizia_db`, `viizia_uploads`) — utiliser `down` sans `-v` pour préserver vos données.

### Réflexe à adopter

Avant de soupçonner :
- ❌ le cache navigateur
- ❌ le cache Symfony (`bin/console cache:clear`)
- ❌ une erreur dans votre code

Vérifiez **d'abord** que le container voit bien vos fichiers à jour. C'est gratuit et règle 80 % des « ça marche pas mais je sais plus pourquoi ».