docs: mise à jour complète de la documentation dans docs/app/
- architecture.md : structure Next.js, modifications Navigation.tsx, page équipe - configuration.md : rings standards adopt|trial|assess|hold, migration - deploiement.md : script Python, Navigation.tsx, processus de build détaillé - developpement.md : nouvelles commandes, scripts, gestion profils équipe - contribution.md : format business, rings standards, métadonnées complètes - guide-page-equipe.md : architecture hybride, script Python, troubleshooting - guide-radar-business.md : rings standards, migration, navigation - troubleshooting.md : nouveau document avec problèmes courants et solutions - README.md : liens mis à jour, nouvelles fonctionnalités - FORMAT-BLIP.md : rings standards adopt|trial|assess|hold
This commit is contained in:
syoul
273
docs/app/troubleshooting.md
Normal file
273
docs/app/troubleshooting.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# 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"' .techradar/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 `.techradar/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"' .techradar/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 .techradar/data/radar -name "*.md" | wc -l
|
||||
# Doit retourner ~38 fichiers
|
||||
```
|
||||
4. Vérifier que `config-business.json` a été copié vers `.techradar/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 Équipe
|
||||
|
||||
#### Page `/team` retourne 404
|
||||
|
||||
**Symptôme** : La page `/team` n'est pas accessible ou retourne une erreur 404.
|
||||
|
||||
**Causes possibles** :
|
||||
- Le fichier `team.html` n'est pas dans `out/`
|
||||
- La page Next.js `team.tsx` n'a pas été créée
|
||||
- Le fichier n'a pas été copié dans `.techradar/public/`
|
||||
|
||||
**Solutions** :
|
||||
1. Vérifier que `public/team.html` existe
|
||||
2. Vérifier que le Dockerfile a bien créé `.techradar/src/pages/team.tsx`
|
||||
3. Vérifier que `team.html` a été copié dans `.techradar/public/` puis dans `out/`
|
||||
4. Vérifier les logs du script `start-business.sh` qui doit copier les fichiers manquants
|
||||
|
||||
**Vérification** :
|
||||
```bash
|
||||
# Dans le conteneur
|
||||
ls -l .techradar/public/team.html
|
||||
ls -l out/team.html
|
||||
ls -l .techradar/src/pages/team.tsx
|
||||
```
|
||||
|
||||
#### Données de visualisation manquantes
|
||||
|
||||
**Symptôme** : Les visualisations de la page équipe sont vides.
|
||||
|
||||
**Cause** : Le fichier `team-visualization-data.json` n'a pas été généré ou n'est pas accessible.
|
||||
|
||||
**Solution** :
|
||||
1. Générer les données :
|
||||
```bash
|
||||
node scripts/generate-team-visualization-data.js
|
||||
```
|
||||
2. Vérifier que le fichier existe dans `public/team-visualization-data.json`
|
||||
3. Vérifier que le fichier a été copié dans `out/` lors du build
|
||||
|
||||
### 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
|
||||
|
||||
### Vérifier les fichiers dans le conteneur
|
||||
|
||||
```bash
|
||||
# Se connecter au conteneur
|
||||
docker exec -it <container-name> /bin/sh
|
||||
|
||||
# Vérifier les fichiers
|
||||
ls -la .techradar/src/pages/team.tsx
|
||||
ls -la .techradar/src/components/Navigation/Navigation.tsx
|
||||
ls -la .techradar/public/team.html
|
||||
ls -la out/team.html
|
||||
|
||||
# Compter les blips
|
||||
find .techradar/data/radar -name "*.md" | wc -l
|
||||
|
||||
# Vérifier la config
|
||||
head -60 .techradar/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"' .techradar/src/components/Navigation/Navigation.tsx
|
||||
|
||||
# Voir le contexte autour du lien
|
||||
grep -A 3 -B 3 'href="/team"' .techradar/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
|
||||
|
||||
Reference in New Issue
Block a user