AJR/TechradarDev
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: mise à jour complète de la documentation dans docs/app/

Browse Source 
- 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
2025-12-09 11:01:29 +01:00
parent 9a055add6f
commit 005ed9ee7f
10 changed files with 1284 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

434
docs/app/guide-page-equipe.md
View File

@@ -9,12 +9,19 @@ Cette page est accessible depuis le radar via le lien **"👥 Équipe"** dans le
## Architecture Technique
La page utilise une architecture hybride :
- **Page Next.js** : `/team` (route Next.js générée automatiquement)
- **Page Next.js** : `/team` (route Next.js générée automatiquement par `Dockerfile.business`)
- **Contenu HTML** : Chargé via iframe depuis `/team.html` (fichier statique)
- **Navigation** : Lien intégré directement dans le composant React `Navigation.tsx`
- **Navigation** : Lien intégré directement dans le composant React `Navigation.tsx` (modifié par script Python)
Cette approche combine les avantages de Next.js (routing, intégration native) avec la flexibilité d'un HTML statique autonome.
### Fichiers impliqués
- **Page Next.js** : `.techradar/src/pages/team.tsx` (créée par `Dockerfile.business`)
- **Page HTML** : `public/team.html` (fichier statique avec visualisations)
- **Données JSON** : `public/team-visualization-data.json` (généré par `scripts/generate-team-visualization-data.js`)
- **Navigation** : `.techradar/src/components/Navigation/Navigation.tsx` (modifiée par script Python)
## Accès
- **URL** : `/team` (route Next.js)
@@ -32,7 +39,7 @@ La page propose trois visualisations complémentaires :
**Fonctionnalités** :
- **Nœuds technologies** :
- Couleur selon le ring (Core=rouge, Strategic=orange, Support=bleu)
- Couleur selon le ring (Adopt=vert, Trial=bleu, Assess=orange, Hold=rouge)
- Taille proportionnelle au nombre de personnes maîtrisant la technologie
- Label avec le nom de la technologie
- **Nœuds membres** :
@@ -48,293 +55,282 @@ La page propose trois visualisations complémentaires :
- Pan : Clic gauche + glisser
- Tooltip : Survol d'un nœud pour voir les détails
**Cas d'usage** :
- Identifier visuellement qui maîtrise quelles technologies
- Repérer les technologies isolées (peu de connexions)
- Visualiser la polyvalence des membres (nombre de connexions)
**Technologie** : Cytoscape.js avec le layout CoSE-Bilkent
### 2. Matrice de Congestion
**Objectif** : Identifier les risques de congestion sur les technologies critiques.
**Objectif** : Identifier les technologies avec faible couverture d'équipe (congestions).
**Fonctionnalités** :
- Affiche uniquement les **technologies core** (critiques pour le business)
- Filtre les membres avec **disponibilité >= 50%**
- Visualisation en scatter plot avec :
- Axe X : Membres de l'équipe
- Axe Y : Technologies core
- Points : Disponibilité du membre sur la technologie
- Taille des points : Disponibilité en pourcentage
- **Axe X** : Membres de l'équipe
- **Axe Y** : Technologies
- **Couleurs** :
- Vert : Technologie maîtrisée par le membre
- Rouge : Technologie non maîtrisée
- Intensité selon le niveau de compétence
**Utilisation** :
- Survol d'un point pour voir les détails (membre, technologie, disponibilité)
- Zoom possible sur le graphique
- Cliquer sur une cellule pour voir les détails
- Filtrer par technologie ou membre
- Identifier visuellement les technologies avec peu de personnes
**Cas d'usage** :
- Identifier les technologies core avec peu de couverture
- Repérer les membres disponibles pour les technologies critiques
- Détecter les risques de congestion (1 seule personne sur une techno core)
**Technologie** : ECharts (heatmap)
### 3. Équipe de Genèse MVP
**Objectif** : Composer automatiquement une équipe minimale pour un MVP en 2 mois avec mobilisation quotidienne.
**Critères de sélection** :
- Technologies : Uniquement `ring: core`
- Membres : Disponibilité >= 50%
- Priorisation : Membres couvrant le plus de technologies core
**Affichage** :
**Fonctionnalités** :
- **Sélection automatique** : Algorithme qui sélectionne les membres selon :
- Disponibilité >= 50%
- Couverture maximale des technologies critiques
- Équilibre des compétences
- **Statistiques** :
- Nombre de membres sélectionnés
- Capacité totale (somme des disponibilités)
- Disponibilité moyenne
- Technologies couvertes / total core
- **Liste des membres** :
- Nom, rôle, niveau de séniorité
- Disponibilité en pourcentage
- Liste des technologies core maîtrisées
- **Alertes** :
- Technologies core non couvertes par l'équipe sélectionnée
- Impact business et niveau de risque (skillGap)
- Pourcentage de technologies couvertes
- Technologies critiques non couvertes
- **Recommandations** :
- Technologies à former
- Compétences manquantes
- Risques identifiés
**Cas d'usage** :
- Composer une équipe pour un MVP rapide
- Identifier les compétences manquantes
- Estimer la capacité disponible pour le développement
**Technologie** : Algorithme JavaScript avec affichage HTML/CSS
## Données Sources
## Données
### Technologies
### Sources de données
Les données des technologies sont extraites depuis :
- **Dossier** : `radar-business/2025-01-15/`
- **Format** : Fichiers Markdown avec métadonnées YAML
- **Champs utilisés** :
- `title` : Nom de la technologie
- `ring` : Anneau (core, strategic, support, legacy)
- `quadrant` : Quadrant business
- `businessImpact` : Impact sur le business
- `teamCoverage` : Nombre de personnes maîtrisant
- `skillGap` : Risque de compétence manquante
- Section "Compétences" : Liste des membres
1. **Profils équipe** : `docs/data/team/*.md` (fichiers Markdown avec métadonnées YAML)
2. **Technologies** : `radar-business/2025-01-15/*.md` (blips avec métadonnées)
### Membres de l'Équipe
### Génération des données
Les données des membres sont extraites depuis :
- **Dossier** : `docs/data/team/`
- **Format** : Fichiers Markdown avec métadonnées YAML
- **Champs utilisés** :
- `name` : Identifiant du membre
- `fullName` : Nom complet
- `role` : Rôle dans l'équipe
- `availability` : Disponibilité en pourcentage
- `seniorityLevel` : Niveau de séniorité
- `skills` : Liste des compétences techniques
Le script `scripts/generate-team-visualization-data.js` :
## Génération des Données
1. **Lit les profils équipe** depuis `docs/data/team/*.md`
2. **Lit les technologies** depuis `radar-business/2025-01-15/*.md`
3. **Génère** `public/team-visualization-data.json` avec :
- `network` : Données réseau (nodes/edges) pour Cytoscape.js
- `congestionMatrix` : Matrice de congestion pour ECharts
- `genesisTeam` : Équipe de genèse MVP avec statistiques
- `technologies` : Liste des technologies avec métadonnées
- `members` : Liste des membres avec compétences
Les visualisations utilisent un fichier JSON généré automatiquement : `public/team-visualization-data.json`
### Régénérer les Données
Si vous modifiez les profils d'équipe ou les technologies, régénérez les données :
### Exécuter la génération
```bash
node scripts/generate-team-visualization-data.js
```
**Ce que fait le script** :
1. Charge toutes les technologies depuis `radar-business/2025-01-15/`
2. Charge tous les membres depuis `docs/data/team/`
3. Extrait les associations technologies ↔ membres
4. Génère les données pour les 3 visualisations
5. Écrit le fichier JSON dans `public/team-visualization-data.json`
**Important** : Régénérer les données après chaque modification des profils équipe ou des technologies.
**Structure des données générées** :
- `network` : Nœuds et liens pour le graphe Cytoscape.js
- `congestionMatrix` : Matrice pour les technologies core
- `genesisTeam` : Équipe de genèse MVP avec statistiques
- `technologies` : Liste complète des technologies
- `members` : Liste complète des membres
## Structure des profils équipe
### Intégration dans le Build
Les profils sont stockés dans `docs/data/team/*.md` avec le format suivant :
La page est automatiquement créée lors du build Docker via le script `scripts/create-team-page.sh` :
```markdown
---
name: "pseudo"
fullName: "Nom complet"
role: "Rôle"
availability: 50
seniorityLevel: expert
yearsExperience: 8
joinDate: "2016-01"
interests: ["Mobile", "Infrastructure"]
skills:
- name: "Flutter"
level: expert
years: 4
lastUsed: "2024-12"
- name: "Python"
level: intermediate
years: 5
lastUsed: "2024-11"
softSkills:
- "Autonomie"
- "Pédagogie"
projects:
- "Projet1"
- "Projet2"
---
Description du membre de l'équipe.
```
### Métadonnées
- **name** : Pseudo unique (utilisé comme identifiant)
- **fullName** : Nom complet
- **role** : Rôle dans l'équipe
- **availability** : Disponibilité en pourcentage (0-100)
- **seniorityLevel** : Niveau de séniorité (junior, intermediate, senior, expert)
- **yearsExperience** : Années d'expérience totales
- **joinDate** : Date d'arrivée (format YYYY-MM)
- **interests** : Centres d'intérêt
- **skills** : Liste des compétences techniques avec niveau, années et dernière utilisation
- **softSkills** : Compétences comportementales
- **projects** : Projets sur lesquels le membre a travaillé
## Processus de build
### Dans le Dockerfile
1. **Création de la page Next.js** : Génère `.techradar/src/pages/team.tsx`
2. **Modification de Navigation** : Ajoute le lien "👥 Équipe" dans `.techradar/src/components/Navigation/Navigation.tsx`
3. **Copie des fichiers** : Assure que `team.html` et `team-visualization-data.json` sont copiés dans `out/`
2. **Modification de Navigation** : Ajoute le lien "👥 Équipe" dans `.techradar/src/components/Navigation/Navigation.tsx` via script Python
3. **Copie des fichiers** : Copie `public/team.html` et `public/team-visualization-data.json` vers `.techradar/public/`
4. **Build Next.js** : Génère les fichiers statiques dans `out/`
5. **Vérification** : Le script `start-business.sh` vérifie que les fichiers sont dans `out/` et les copie si nécessaire
Le script est exécuté automatiquement dans `Dockerfile.business` avant le build Next.js.
### Script Python pour Navigation.tsx
**Pour régénérer les données de visualisation** :
Le script `/tmp/add_team_link.py` dans le Dockerfile :
```bash
node scripts/generate-team-visualization-data.js
```
1. **Supprime tous les liens Équipe existants** : Évite les doublons
2. **Ajoute un seul lien Équipe** : Après le lien "Vue d'ensemble"
3. **Vérifie le résultat** : S'assure qu'il n'y a qu'un seul lien
**Pour tester localement** :
**Important** : Les scripts JavaScript (`strategie-script.js`, `strategie-link.js`) qui ajoutaient des liens dans le header ont été désactivés pour éviter les doublons.
```bash
# Générer les données
node scripts/generate-team-visualization-data.js
# Créer la page Next.js et modifier Navigation
./scripts/create-team-page.sh
# Démarrer le serveur
npm run serve-business
```
## Technologies Utilisées
## Technologies utilisées
### Bibliothèques JavaScript
- **Cytoscape.js** (v3.26.0) : Graphe de réseau interactif
- Extension : `cytoscape-cose-bilkent` pour le layout automatique
- **ECharts** (v5.4.3) : Graphiques interactifs (matrice de congestion)
- **Cytoscape.js** : Graphique réseau interactif
- **Cytoscape CoSE-Bilkent** : Layout algorithm pour le graphique
- **ECharts** : Matrice de congestion (heatmap)
- **Vanilla JavaScript** : Logique de l'équipe de genèse MVP
### Chargement
### Chargement des données
Les bibliothèques sont chargées via CDN dans la page HTML (`public/team.html`) :
- Pas besoin d'installation locale
- Mise à jour possible en modifiant les URLs dans `public/team.html`
- Les bibliothèques sont chargées dans l'iframe, isolées du reste de l'application
Les données sont chargées depuis `/team-visualization-data.json` via `fetch()` au chargement de la page.
## Personnalisation
## Utilisation
### Modifier le Seuil de Disponibilité
### Visualiser les compétences
Pour l'équipe de genèse MVP, le seuil est fixé à **50%**. Pour le modifier :
1. Ouvrir l'onglet **"Graphe Réseau"**
2. Explorer les connexions entre technologies et membres
3. Identifier les technologies avec beaucoup de personnes (gros nœuds)
4. Identifier les technologies avec peu de personnes (petits nœuds = congestions)
1. Ouvrir `scripts/generate-team-visualization-data.js`
2. Modifier la ligne dans `generateCongestionMatrix()` :
```javascript
const availableMembers = members.filter(m => m.availability >= 50);
```
3. Modifier la ligne dans `generateGenesisTeam()` :
```javascript
const availableMembers = members.filter(m => m.availability >= 50);
```
4. Régénérer les données
### Modifier les Couleurs du Graphe
Les couleurs sont définies dans `public/team.html` dans la fonction `initNetworkGraph()` :
```javascript
const ringColor = {
'core': '#ff4444',
'strategic': '#ff8800',
'support': '#4488ff',
'legacy': '#888888'
}[tech.ring] || '#999999';
```
### Ajouter une Visualisation
Pour ajouter une nouvelle visualisation :
1. Ajouter un onglet dans le HTML
2. Créer la fonction d'initialisation
3. Ajouter les données nécessaires dans `generate-team-visualization-data.js`
4. Appeler la fonction dans `initVisualizations()`
## Cas d'Usage Concrets
### Identifier une Congestion Critique
### Identifier les congestions
1. Ouvrir l'onglet **"Matrice Congestion"**
2. Repérer les technologies core avec peu ou pas de points
3. Vérifier dans l'onglet **"Graphe Réseau"** qui maîtrise cette technologie
4. Si une seule personne : **Risque critique** (départ = blocage)
2. Repérer les colonnes (technologies) avec beaucoup de cases rouges
3. Ces technologies ont une faible couverture d'équipe
4. Actions recommandées :
- Former l'équipe
- Recruter
- Documenter
### Composer une Équipe pour un Projet
1. Ouvrir l'onglet **"Équipe Genèse MVP"**
2. Vérifier les technologies couvertes
3. Si des technologies sont non couvertes :
- Former un membre existant
- Recruter une compétence
- Changer de technologie
4. Estimer la capacité disponible (somme des disponibilités)
2. L'équipe est automatiquement sélectionnée selon :
- Disponibilité >= 50%
- Couverture maximale des technologies
3. Consulter les statistiques :
- Technologies couvertes
- Technologies manquantes
- Recommandations
### Analyser la Polyvalence
## Personnalisation
1. Ouvrir l'onglet **"Graphe Réseau"**
2. Repérer les membres avec beaucoup de connexions (polyvalents)
3. Repérer les membres avec peu de connexions (spécialisés)
4. Équilibrer l'équipe selon les besoins
### Modifier le seuil de disponibilité
## Limitations Actuelles
Pour l'équipe de genèse MVP, le seuil est fixé à **50%**. Pour le modifier :
- **Seuil fixe** : Disponibilité >= 50% pour l'équipe de genèse (non configurable dans l'UI)
- **Technologies core uniquement** : La matrice de congestion ne montre que les technologies `ring: core`
- **Pas de filtres interactifs** : Impossible de filtrer par quadrant, niveau, etc. dans l'interface
- **Données statiques** : Nécessite de régénérer le JSON après chaque modification
1. Ouvrir `scripts/generate-team-visualization-data.js`
2. Modifier la constante `MIN_AVAILABILITY` dans la fonction `generateGenesisTeam()`
3. Régénérer les données : `node scripts/generate-team-visualization-data.js`
## Améliorations Futures Possibles
### Ajouter de nouvelles visualisations
- Filtres interactifs (quadrant, ring, niveau de compétence)
- Export PDF/PNG des visualisations
- Historique des équipes de genèse
- Calcul automatique de la charge de travail
- Suggestions de formation basées sur les gaps
- Intégration avec un système de planning (Gantt)
1. Modifier `public/team.html`
2. Ajouter un nouvel onglet dans la section `.tabs`
3. Ajouter le contenu dans une nouvelle section `.tab-content`
4. Implémenter la logique JavaScript pour charger et afficher les données
## Dépannage
## Maintenance
### Mettre à jour les profils équipe
1. Modifier les fichiers dans `docs/data/team/*.md`
2. Régénérer les données : `node scripts/generate-team-visualization-data.js`
3. Commiter les deux fichiers (profils + données JSON)
### Ajouter un nouveau membre
1. Créer un fichier `docs/data/team/pseudo.md`
2. Remplir toutes les métadonnées
3. Régénérer les données
4. Vérifier que le membre apparaît dans les visualisations
### Mettre à jour les compétences
1. Modifier la section `skills` dans le profil équipe
2. Régénérer les données
3. Vérifier que les connexions sont mises à jour dans le graphe
## Troubleshooting
### Le lien "👥 Équipe" n'apparaît pas dans le header
1. Vérifier que le script `create-team-page.sh` s'est exécuté correctement
2. Vérifier dans les logs Docker que le script a bien modifié `Navigation.tsx`
3. Vérifier que le fichier `.techradar/src/components/Navigation/Navigation.tsx` contient le lien
**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
### La page `/team` retourne une 404
**Solutions** :
1. Vérifier les logs Docker lors du build
2. Vérifier que le fichier `.techradar/src/components/Navigation/Navigation.tsx` existe
3. Rebuild avec `--no-cache` pour forcer l'exécution du script
1. Vérifier que `team.html` est bien copié dans `out/` après le build
2. Vérifier les logs du Dockerfile pour voir si la copie a réussi
3. Vérifier que `scripts/start-business.sh` copie bien les fichiers au démarrage
4. Vérifier que la page Next.js `team.tsx` a bien été créée dans `.techradar/src/pages/`
### La page `/team` retourne 404
### Les visualisations ne se chargent pas
**Causes possibles** :
- Le fichier `team.html` n'est pas dans `out/`
- La page Next.js `team.tsx` n'a pas été créée
1. Vérifier que `team-visualization-data.json` est accessible à `/team-visualization-data.json`
2. Vérifier la console du navigateur pour les erreurs de chargement
3. Régénérer les données avec `node scripts/generate-team-visualization-data.js`
4. Vérifier que les fichiers Markdown des profils sont bien formatés
**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 `out/`
### Support
### Les visualisations sont vides
Pour toute question ou problème :
- Consulter les logs du script de génération
- Vérifier que les fichiers Markdown sont bien formatés
- Vérifier que le fichier JSON est bien généré et accessible
- Consulter les logs Docker pour voir l'exécution de `create-team-page.sh`
**Causes possibles** :
- Le fichier `team-visualization-data.json` n'a pas été généré
- Le fichier n'est pas accessible depuis `/team.html`
## Fichiers Associés
**Solutions** :
1. Générer les données : `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/`
4. Vérifier la console du navigateur pour les erreurs JavaScript
### Fichiers Source
- **Page HTML** : `public/team.html` (contenu principal avec visualisations)
- **Données JSON** : `public/team-visualization-data.json` (données générées)
### Les données ne sont pas à jour
**Solution** : Régénérer les données après chaque modification :
```bash
node scripts/generate-team-visualization-data.js
```
## Fichiers associés
- **Page HTML** : `public/team.html` (interface utilisateur)
- **Données JSON** : `public/team-visualization-data.json` (généré)
- **Script de génération** : `scripts/generate-team-visualization-data.js`
- **Profils équipe** : `docs/data/team/*.md` (fichiers Markdown avec métadonnées YAML)
- **Technologies** : `radar-business/2025-01-15/*.md` (fichiers Markdown du radar)
- **Technologies** : `radar-business/2025-01-15/*.md` (blips avec métadonnées)
- **Page Next.js** : `.techradar/src/pages/team.tsx` (générée par le Dockerfile)
- **Navigation modifiée** : `.techradar/src/components/Navigation/Navigation.tsx` (modifiée par le Dockerfile)
### Scripts
- **Génération des données** : `scripts/generate-team-visualization-data.js`
- Charge les technologies et membres
- Génère le fichier JSON pour les visualisations
- **Création de la page Next.js** : `scripts/create-team-page.sh`
- Crée `.techradar/src/pages/team.tsx` (page Next.js avec iframe)
- Modifie `.techradar/src/components/Navigation/Navigation.tsx` (ajoute le lien)
### Fichiers Générés (pendant le build)
- **Page Next.js** : `.techradar/src/pages/team.tsx` (générée par le script)
- **Navigation modifiée** : `.techradar/src/components/Navigation/Navigation.tsx` (modifiée par le script)
- **Fichiers dans out/** : `out/team.html` et `out/team-visualization-data.json` (copiés après build)
### Configuration
- **Dockerfile** : `Dockerfile.business` (exécute `create-team-page.sh` avant le build)
- **Script de démarrage** : `scripts/start-business.sh` (vérifie et copie les fichiers au démarrage)
## Ressources
- [Guide de développement](./developpement.md)
- [Guide de déploiement](./deploiement.md)
- [Guide de dépannage](./troubleshooting.md)
- Documentation Cytoscape.js : https://js.cytoscape.org/
- Documentation ECharts : https://echarts.apache.org/