TechradarDev/docs/app/troubleshooting.md

# Guide de dépannage

## Problèmes courants et solutions

### Navigation et liens

#### Doublons de liens dans la navigation

**Symptôme** : Plusieurs liens "Équipe" ou autres liens apparaissent en double dans le header.

**Causes possibles** :
- Le script Python a ajouté le lien plusieurs fois
- Les scripts JavaScript ajoutent encore des liens (fonctions non désactivées)
- Le fichier Navigation.tsx contient déjà des liens dupliqués

**Solutions** :
1. Vérifier que les fonctions JavaScript sont bien désactivées :
   - `public/strategie-script.js` : `addLinksToHeader()` doit être commentée
   - `public/strategie-link.js` : `addStrategyLinkToHeader()` doit être commentée
2. Rebuild l'image Docker avec `--no-cache` pour forcer l'exécution du script Python de nettoyage
3. Vérifier dans les logs Docker que le script Python a bien supprimé les doublons

**Vérification** :
```bash
# Dans le conteneur
grep -c 'href="/team"' radar-app/src/components/Navigation/Navigation.tsx
# Doit retourner 1 (un seul lien)
```

#### Lien "Équipe" n'apparaît pas

**Symptôme** : Le lien "👥 Équipe" n'est pas visible dans la navigation.

**Causes possibles** :
- Le script Python n'a pas été exécuté
- Le fichier Navigation.tsx n'a pas été trouvé
- Erreur dans le script Python

**Solutions** :
1. Vérifier les logs Docker lors du build pour voir si le script Python s'est exécuté
2. Vérifier que le fichier `radar-app/src/components/Navigation/Navigation.tsx` existe
3. Vérifier que le script Python a bien trouvé l'emplacement pour insérer le lien
4. Rebuild avec `--no-cache` pour forcer l'exécution

**Vérification** :
```bash
# Dans le conteneur
grep 'href="/team"' radar-app/src/components/Navigation/Navigation.tsx
# Doit retourner le lien
```

### Données du radar

#### Seulement 2 blips affichés (Ansible et OpenTofu)

**Symptôme** : Le radar n'affiche que quelques blips au lieu de tous.

**Causes possibles** :
- Les blips utilisent des rings non définis dans la config (core, strategic, support au lieu de adopt, trial, assess, hold)
- Les données business n'ont pas été copiées correctement
- La config business n'est pas utilisée

**Solutions** :
1. Vérifier que tous les blips utilisent les rings standards : `adopt`, `trial`, `assess`, `hold`
2. Vérifier que `radar-business/config-business.json` contient bien les rings standards
3. Vérifier dans les logs Docker que les données ont été copiées :
   ```bash
   # Dans le conteneur
   find radar-app/data/radar -name "*.md" | wc -l
   # Doit retourner ~38 fichiers
   ```
4. Vérifier que `config-business.json` a été copié vers `radar-app/data/config.json`

**Migration des rings** :
```bash
# Migrer tous les blips vers les rings standards
cd radar-business/2025-01-15
find . -name "*.md" -exec sed -i 's/^ring: core$/ring: adopt/' {} \;
find . -name "*.md" -exec sed -i 's/^ring: strategic$/ring: assess/' {} \;
find . -name "*.md" -exec sed -i 's/^ring: support$/ring: adopt/' {} \;
```

#### Erreur "invalid ring"

**Symptôme** : Des erreurs "invalid ring" apparaissent dans les logs.

**Cause** : Les blips utilisent des rings qui ne sont pas définis dans la configuration.

**Solution** : Vérifier que tous les rings utilisés dans les blips sont bien définis dans `config-business.json`.

### Page Equipe

#### Page `/team` affiche le radar au lieu des visualisations

**Symptome** : La page `/team` affiche le contenu du radar au lieu des visualisations equipe.

**Causes possibles** :
- Le script `team-block-script.js` n'est pas charge
- Le script `patch_document.py` n'a pas modifie `_document.tsx`
- Le script n'a pas pu remplacer le DOM

**Solutions** :
1. Verifier la console du navigateur (F12) pour les erreurs JavaScript
2. Verifier que le script `team-block-script.js` est inclus dans le HTML :
   ```bash
   curl -s http://localhost:3006/team/ | grep team-block-script
   ```
3. Rebuild avec `--no-cache` pour forcer l'execution des scripts Python

**Verification** :
```bash
# Dans le conteneur
ls -l radar-app/public/team-block-script.js
grep "team-block-script" radar-app/src/pages/_document.tsx
```

#### Page `/team` retourne 404

**Symptome** : La page `/team` n'est pas accessible ou retourne une erreur 404.

**Causes possibles** :
- La page Next.js `team.tsx` n'a pas ete creee
- Le serveur utilise `--single` qui redirige vers index.html

**Solutions** :
1. Verifier que le Dockerfile a bien cree `radar-app/src/pages/team.tsx`
2. Verifier que `scripts/start-business.sh` ne contient pas l'option `--single`
3. Verifier les logs du build Docker

**Verification** :
```bash
# Dans le conteneur
ls -l radar-app/src/pages/team.tsx
ls -l out/team/index.html
```

#### Donnees de visualisation manquantes ou erreur de chargement

**Symptome** : Les visualisations de la page equipe sont vides ou affichent une erreur.

**Causes possibles** :
- Le fichier `team-visualization-data.json` n'a pas ete genere
- Le fichier n'est pas accessible depuis le navigateur
- Erreur dans le chargement des bibliotheques (Cytoscape, ECharts)

**Solutions** :
1. Generer les donnees :
   ```bash
   node scripts/generate-team-visualization-data.js
   ```
2. Verifier que le fichier existe dans `public/team-visualization-data.json`
3. Verifier l'acces direct : `http://localhost:3006/team-visualization-data.json`
4. Verifier la console du navigateur pour les erreurs JavaScript
5. Verifier la connexion internet (les bibliotheques sont chargees depuis CDN)

### Build Docker

#### Erreur "dockerfile parse error"

**Symptôme** : Erreur de syntaxe dans le Dockerfile.

**Causes possibles** :
- Commandes shell mal formatées dans les instructions RUN
- Variables mal échappées
- Heredocs mal fermés

**Solution** : Vérifier la syntaxe du Dockerfile, notamment :
- Les instructions RUN doivent être sur une seule ligne ou utiliser `\` pour continuer
- Les heredocs doivent être correctement fermés
- Les variables shell doivent être échappées avec `$$`

#### Build utilise le cache alors que les fichiers ont changé

**Symptôme** : Les modifications ne sont pas prises en compte après un rebuild.

**Cause** : Docker utilise le cache des couches précédentes.

**Solution** : Rebuild avec `--no-cache` :
```bash
docker build --no-cache -f Dockerfile.business -t laplank-techradar-radar-business .
```

Dans Portainer, cocher l'option "No cache" lors du rebuild de la stack.

#### Script Python échoue avec exit code 2

**Symptôme** : Le script Python pour modifier Navigation.tsx échoue.

**Causes possibles** :
- Le fichier Navigation.tsx n'existe pas encore
- Problème de fin de ligne
- Erreur de syntaxe Python

**Solutions** :
1. Vérifier que le fichier existe avant d'exécuter le script
2. Vérifier les logs pour voir l'erreur exacte
3. Le script devrait afficher des messages de débogage

### Déploiement

#### Les modifications ne sont pas visibles après déploiement

**Symptôme** : Après un déploiement, les changements ne sont pas visibles.

**Causes possibles** :
- Cache du navigateur
- Cache Docker
- Fichiers non copiés correctement

**Solutions** :
1. Vider le cache du navigateur (Ctrl+Shift+R ou Cmd+Shift+R)
2. Rebuild Docker avec `--no-cache`
3. Vérifier les logs pour confirmer que les fichiers ont été copiés

#### Erreur de permissions dans le conteneur

**Symptôme** : Erreurs de permissions lors de l'exécution.

**Cause** : Problème de permissions sur les fichiers ou répertoires.

**Solution** : Vérifier les permissions dans le Dockerfile et s'assurer que les fichiers sont accessibles.

### Scripts

#### Script generate-team-visualization-data.js ne trouve pas les fichiers

**Symptôme** : Le script ne peut pas lire les fichiers de profils ou de technologies.

**Cause** : Chemins incorrects ou fichiers manquants.

**Solution** :
1. Vérifier que les fichiers existent :
   - `docs/data/team/*.md`
   - `radar-business/2025-01-15/*.md`
2. Exécuter le script depuis la racine du projet
3. Vérifier les chemins dans le script

## Commandes utiles pour le débogage

### Verifier les fichiers dans le conteneur

```bash
# Se connecter au conteneur
docker exec -it <container-name> /bin/sh

# Verifier les fichiers de la page equipe
ls -la radar-app/src/pages/team.tsx
ls -la radar-app/public/team-block-script.js
ls -la out/team-block-script.js
ls -la out/team-visualization-data.json

# Verifier les modifications
grep "team-block-script" radar-app/src/pages/_document.tsx
ls -la radar-app/src/components/Navigation/Navigation.tsx

# Compter les blips
find radar-app/data/radar -name "*.md" | wc -l

# Verifier la config
head -60 radar-app/data/config.json
```

### Vérifier les logs

```bash
# Logs du conteneur
docker logs <container-name>

# Logs en temps réel
docker logs -f <container-name>

# Dernières lignes
docker logs --tail=100 <container-name>
```

### Vérifier les rings dans les blips

```bash
# Lister tous les rings utilisés
cd radar-business/2025-01-15
grep -h "^ring:" *.md | sort | uniq -c

# Doit retourner uniquement : adopt, trial, assess, hold
```

### Vérifier les liens dans Navigation.tsx

```bash
# Compter les liens Équipe
grep -c 'href="/team"' radar-app/src/components/Navigation/Navigation.tsx

# Voir le contexte autour du lien
grep -A 3 -B 3 'href="/team"' radar-app/src/components/Navigation/Navigation.tsx
```

## Obtenir de l'aide

Si le problème persiste :
1. Vérifier les logs Docker complets
2. Vérifier la documentation dans `docs/app/`
3. Vérifier les issues sur le dépôt Git
4. Contacter l'équipe technique