TechradarDev/docs/app/guide-page-equipe.md

Guide de la Page Equipe & Technologies

Introduction

La page Equipe & Technologies (/team) est une interface de visualisation interactive qui permet d'analyser les competences de l'equipe, d'identifier les congestions (technologies avec peu de personnes) et de composer une equipe de genese pour un MVP.

Cette page est accessible depuis le radar via le lien "Equipe" dans le header de navigation.

Architecture Technique

La page utilise une architecture basee sur l'injection de contenu cote client :

• Script principal : public/team-block-script.js charge par Next.js via _document.tsx
• Remplacement DOM : Le script detecte la route /team et remplace le contenu du body
• Chargement dynamique : Cytoscape.js et ECharts sont charges depuis CDN
• Donnees JSON : public/team-visualization-data.json genere par script Node.js
• Navigation : Lien integre dans Navigation.tsx (modifie par script Python lors du build)

Cette approche evite les conflits SSR tout en permettant des visualisations interactives riches.

Fichiers impliques

• Script principal : public/team-block-script.js (injection du contenu et visualisations)
• Page Next.js : .techradar/src/pages/team.tsx (page vide, le script remplace le contenu)
• Donnees JSON : public/team-visualization-data.json (genere par scripts/generate-team-visualization-data.js)
• Navigation : .techradar/src/components/Navigation/Navigation.tsx (modifiee par script Python)
• Document modifie : .techradar/src/pages/_document.tsx (modifie pour charger le script)

Acces

• URL : /team ou /team/
• Lien de navigation : Disponible dans le header du radar (bouton "Equipe")
• Authentification : Meme protection que le radar (mot de passe laplank-radar)

Fonctionnalites

La page propose trois visualisations complementaires accessibles via des onglets :

1. Graphe Reseau

Objectif : Visualiser les connexions entre technologies et membres de l'equipe.

Fonctionnalites :

• Noeuds technologies :
  • Couleur selon le ring (Adopt=vert, Trial=bleu, Assess=orange, Hold=rouge)
  • Taille proportionnelle au nombre de personnes maitrisant la technologie
  • Label avec le nom de la technologie
• Noeuds membres :
  • Couleur verte
  • Taille proportionnelle a la disponibilite
  • Label avec le nom du membre
• Liens :
  • Connectent les technologies aux membres qui les maitrisent
  • Epaisseur selon le niveau de competence

Utilisation :

• Zoom : Molette de la souris ou pincement sur mobile
• Pan : Clic gauche + glisser
• Animation : Le graphe s'organise automatiquement au chargement

Technologie : Cytoscape.js avec le layout CoSE (integre)

2. Matrice de Congestion

Objectif : Identifier les technologies avec faible couverture d'equipe (congestions).

Fonctionnalites :

• Axe X : Membres de l'equipe
• Axe Y : Technologies (uniquement les technologies "adopt")
• Points verts : Indiquent qu'un membre maitrise une technologie
• Taille des points : Proportionnelle a la disponibilite du membre

Utilisation :

• Survoler un point pour voir les details (membre, technologie, disponibilite)
• Identifier visuellement les technologies avec peu de personnes (peu de points sur une ligne)

Note : Seules les technologies avec ring: adopt sont affichees dans la matrice, car ce sont les technologies fondamentales en production.

Technologie : ECharts (scatter plot)

3. Equipe de Genese MVP

Objectif : Composer automatiquement une equipe minimale pour un MVP en 2 mois avec mobilisation quotidienne.

Fonctionnalites :

• Selection automatique : Algorithme qui selectionne les membres selon :
  • Disponibilite >= 50%
  • Couverture maximale des technologies critiques (technologies avec ring: adopt)
  • Equilibre des competences
• Statistiques :
  • Nombre de membres selectionnes
  • Capacite totale (somme des disponibilites)
  • Disponibilite moyenne
  • Technologies couvertes / total
• Cartes membres :
  • Nom et role
  • Niveau de seniorite
  • Disponibilite
  • Technologies maitrisees
• Alertes :
  • Technologies critiques non couvertes (en rouge)
  • Impact business et skill gap pour chaque technologie manquante

Technologie : HTML/CSS genere dynamiquement par JavaScript

Donnees

Sources de donnees

1. Profils equipe : docs/data/team/*.md (fichiers Markdown avec metadonnees YAML)
2. Technologies : radar-business/2025-01-15/*.md (blips avec metadonnees)

Generation des donnees

Le script scripts/generate-team-visualization-data.js :

1. Lit les profils equipe depuis docs/data/team/*.md
2. Lit les technologies depuis radar-business/2025-01-15/*.md
3. Genere public/team-visualization-data.json avec :
   • network : Donnees reseau (nodes/edges) pour Cytoscape.js
   • congestionMatrix : Matrice de congestion pour ECharts
   • genesisTeam : Equipe de genese MVP avec statistiques
   • technologies : Liste des technologies avec metadonnees
   • members : Liste des membres avec competences
   • generatedAt : Date de generation

Executer la generation

node scripts/generate-team-visualization-data.js

Important : Regenerer les donnees apres chaque modification des profils equipe ou des technologies.

Structure des profils equipe

Les profils sont stockes dans docs/data/team/*.md avec le format suivant :

---
name: "pseudo"
fullName: "Nom complet"
role: "Role"
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"
  - "Pedagogie"
projects:
  - "Projet1"
  - "Projet2"
---

Description du membre de l'equipe.

Metadonnees

• name : Pseudo unique (utilise comme identifiant)
• fullName : Nom complet
• role : Role dans l'equipe
• availability : Disponibilite en pourcentage (0-100)
• seniorityLevel : Niveau de seniorite (junior, intermediate, senior, expert)
• yearsExperience : Annees d'experience totales
• joinDate : Date d'arrivee (format YYYY-MM)
• interests : Centres d'interet
• skills : Liste des competences techniques avec niveau, annees et derniere utilisation
• softSkills : Competences comportementales
• projects : Projets sur lesquels le membre a travaille

Processus de build

Dans le Dockerfile

1. Copie des fichiers publics : public/team-block-script.js et public/team-visualization-data.json vers .techradar/public/
2. Creation de la page Next.js : Genere .techradar/src/pages/team.tsx (page vide)
3. Modification de _document.tsx : Ajoute le chargement de team-block-script.js avec strategy="beforeInteractive"
4. Modification de Navigation : Ajoute le lien "Equipe" dans Navigation.tsx via script Python
5. Build Next.js : Genere les fichiers statiques dans out/
6. Copie finale : S'assure que les fichiers team sont dans out/

Script Python pour Navigation.tsx

Le script docker/add_team_link.py :

1. Supprime tous les liens Equipe existants : Evite les doublons
2. Ajoute un seul lien Equipe : Apres le lien "Vue d'ensemble"
3. Verifie le resultat : S'assure qu'il n'y a qu'un seul lien

Script Python pour _document.tsx

Le script docker/patch_document.py :

1. Ajoute l'import de Script : Si pas deja present
2. Ajoute le chargement du script : team-block-script.js avec strategy="beforeInteractive"

Technologies utilisees

Bibliotheques JavaScript (chargees depuis CDN)

• Cytoscape.js : Graphique reseau interactif (v3.26.0)
• ECharts : Matrice de congestion scatter plot (v5.4.3)

Layout du graphe

Le graphe reseau utilise le layout CoSE (Compound Spring Embedder) integre a Cytoscape.js. Ce layout :

• Organise les noeuds avec un algorithme force-directed
• Prend en compte les labels pour eviter les chevauchements
• S'anime lors du chargement initial

Chargement des donnees

Les donnees sont chargees depuis /team-visualization-data.json via fetch() au chargement de la page.

Fonctionnement du script

Le script team-block-script.js fonctionne ainsi :

1. Detection de la route : Verifie si le chemin commence par /team
2. Remplacement du DOM : Injecte le HTML de la page (header, onglets, containers)
3. Injection du CSS : Ajoute les styles pour la page
4. Chargement des bibliotheques : Charge Cytoscape et ECharts depuis CDN
5. Chargement des donnees : Fetch /team-visualization-data.json
6. Initialisation des visualisations : Cree le graphe, la matrice et l'equipe de genese
7. Gestion des onglets : Permet de basculer entre les trois visualisations

Utilisation

Visualiser les competences

1. Ouvrir l'onglet "Graphe Reseau"
2. Explorer les connexions entre technologies et membres
3. Identifier les technologies avec beaucoup de personnes (gros noeuds)
4. Identifier les technologies avec peu de personnes (petits noeuds = congestions)

Identifier les congestions

1. Ouvrir l'onglet "Matrice Congestion"
2. Reperer les lignes (technologies) avec peu de points verts
3. Ces technologies ont une faible couverture d'equipe
4. Actions recommandees :
   • Former l'equipe
   • Recruter
   • Documenter

Composer une Equipe pour un Projet

1. Ouvrir l'onglet "Equipe Genese MVP"
2. L'equipe est automatiquement selectionnee selon :
   • Disponibilite >= 50%
   • Couverture maximale des technologies
3. Consulter les statistiques et les cartes membres
4. Verifier les technologies non couvertes (en rouge)

Personnalisation

Modifier le seuil de disponibilite

Pour l'equipe de genese MVP, le seuil est fixe a 50%. Pour le modifier :

1. Ouvrir scripts/generate-team-visualization-data.js
2. Modifier le filtre m.availability >= 50 dans les fonctions generateCongestionMatrix() et generateGenesisTeam()
3. Regenerer les donnees : node scripts/generate-team-visualization-data.js

Note : Les technologies critiques utilisees pour la selection sont celles avec ring: adopt. Pour modifier ce critere, changer le filtre t.ring === 'adopt' dans generateGenesisTeam().

Modifier le layout du graphe

Le layout est configure dans public/team-block-script.js dans la fonction initNetwork() :

layout: {
  name: 'cose',
  nodeDimensionsIncludeLabels: true,
  idealEdgeLength: 100,
  nodeRepulsion: 4500,
  gravity: 0.25,
  numIter: 1000,
  animate: true,
  animationDuration: 800
}

Parametres disponibles :

• nodeRepulsion : Force de repulsion entre noeuds (plus eleve = plus espaces)
• gravity : Force de gravite vers le centre
• numIter : Nombre d'iterations de l'algorithme
• animationDuration : Duree de l'animation en ms

Maintenance

Mettre a jour les profils equipe

1. Modifier les fichiers dans docs/data/team/*.md
2. Regenerer les donnees : node scripts/generate-team-visualization-data.js
3. Commiter les deux fichiers (profils + donnees JSON)
4. Rebuild Docker pour deployer

Ajouter un nouveau membre

1. Creer un fichier docs/data/team/pseudo.md
2. Remplir toutes les metadonnees (voir format ci-dessus)
3. Regenerer les donnees
4. Verifier que le membre apparait dans les visualisations

Mettre a jour les competences

1. Modifier la section skills dans le profil equipe
2. Regenerer les donnees
3. Verifier que les connexions sont mises a jour dans le graphe

Troubleshooting

Le lien "Equipe" n'apparait pas dans le header

Causes possibles :

• Le script Python n'a pas ete execute
• Le fichier Navigation.tsx n'a pas ete trouve
• Erreur dans le script Python

Solutions :

1. Verifier les logs Docker lors du build
2. Verifier que le fichier .techradar/src/components/Navigation/Navigation.tsx existe
3. Rebuild avec --no-cache pour forcer l'execution du script

La page /team affiche le radar au lieu des visualisations

Causes possibles :

• Le script team-block-script.js n'est pas charge
• Le script n'est pas modifie dans _document.tsx

Solutions :

1. Verifier la console du navigateur (F12) pour les erreurs
2. Verifier que le script patch_document.py a ete execute lors du build
3. Rebuild avec --no-cache

Les visualisations 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 les donnees

Solutions :

1. Generer les donnees : node scripts/generate-team-visualization-data.js
2. Verifier que le fichier existe dans public/team-visualization-data.json
3. Verifier la console du navigateur pour les erreurs JavaScript
4. Tester l'acces direct : http://localhost:3006/team-visualization-data.json

Le graphe ne s'affiche pas

Causes possibles :

• Cytoscape.js n'a pas pu etre charge depuis CDN
• Erreur dans la configuration du layout

Solutions :

1. Verifier la connexion internet (CDN)
2. Verifier la console pour les erreurs de chargement
3. Verifier que le layout cose est bien utilise (pas cose-bilkent)

Les donnees ne sont pas a jour

Solution : Regenerer les donnees apres chaque modification :

node scripts/generate-team-visualization-data.js

Puis rebuild Docker :

docker compose -f docker-compose.business.yml build --no-cache
docker compose -f docker-compose.business.yml up -d

Fichiers associes

• Script principal : public/team-block-script.js (injection et visualisations)
• Page Next.js : docker/team-page.tsx (page vide copiee vers .techradar/src/pages/team.tsx)
• Donnees JSON : public/team-visualization-data.json (genere)
• Script de generation : scripts/generate-team-visualization-data.js
• Profils equipe : docs/data/team/*.md (fichiers Markdown avec metadonnees YAML)
• Technologies : radar-business/2025-01-15/*.md (blips avec metadonnees)
• Script Navigation : docker/add_team_link.py (ajoute le lien dans Navigation.tsx)
• Script Document : docker/patch_document.py (ajoute le chargement du script)

Ressources

• Guide de developpement
• Guide de deploiement
• Guide de depannage
• Documentation Cytoscape.js : https://js.cytoscape.org/
• Documentation ECharts : https://echarts.apache.org/