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

92
docs/app/README.md
View File

@@ -12,6 +12,8 @@ Le radar est organisé en quatre quadrants et quatre anneaux (rings) pour classi
Cette documentation est organisée en plusieurs sections :
### Documentation technique
- **[Architecture](./architecture.md)** - Structure du projet, organisation des fichiers et composants
- **[Configuration](./configuration.md)** - Configuration du radar, quadrants, anneaux et personnalisation
- **[Développement](./developpement.md)** - Guide pour développer et tester localement
@@ -19,13 +21,14 @@ Cette documentation est organisée en plusieurs sections :
- **[Contribution](./contribution.md)** - Guide pour ajouter de nouvelles technologies au radar
- **[Guide Radar Business](./guide-radar-business.md)** - Guide d'utilisation du radar technologique Laplank
- **[Page Équipe & Technologies](./guide-page-equipe.md)** - Documentation de la page de visualisation équipe/technologies
- **[Dépannage](./troubleshooting.md)** - Guide de résolution des problèmes courants
### Données du Radar Technologique Laplank
Les données utilisées par l'application sont dans le dossier [`../data/`](../data/) :
- **[Technologies Duniter](../data/technologies-duniter.md)** - Liste des technologies de l'écosystème Duniter/Ğ1
- **[Profil Team](../data/profil-team.md)** - Profils et compétences des membres de l'équipe
- **[Profils Team](../data/team/)** - Profils individuels des membres de l'équipe (fichiers Markdown)
- **[Stratégie d'Évolution Technique](../data/strategie-evolution-technique.md)** - Vision et roadmap technique
- **[Stratégie Business](../data/strategie-business.md)** - Analyse stratégique business
- **[Analyse Stratégique](../data/analyse-strategique.md)** - Rapport d'analyse généré automatiquement
@@ -33,6 +36,7 @@ Les données utilisées par l'application sont dans le dossier [`../data/`](../d
## Liens utiles
- **Radar en ligne** : https://www.coeurbox.syoul.fr
- **Radar Technologique Laplank** : http://laplank.techradar.syoul.fr:3006
- **Dépôt Git** : https://git.open.us.org/AJR/TechradarDev
- **Framework source** : https://github.com/AOEpeople/aoe_technology_radar
@@ -64,3 +68,89 @@ Le serveur démarre sur http://localhost:3006
Pour plus de détails, consultez le [guide de développement](./developpement.md) et le [guide du radar technologique Laplank](./guide-radar-business.md).
## Fonctionnalités principales
### Radar Technologique
- **Visualisation interactive** : Graphique radar avec zoom et filtres
- **Historique par release** : Suivi de l'évolution des technologies au fil du temps
- **Quadrants business** : Classification selon l'impact business
- **Anneaux classiques** : Hold, Assess, Trial, Adopt
- **Filtrage par tags** : Recherche et filtrage des technologies
- **Pages de stratégie** : Accès à la stratégie technique, business et opportunités
### Page Équipe & Technologies
- **Graphe réseau** : Visualisation des connexions technologies/membres
- **Matrice de congestion** : Identification des technologies avec faible couverture
- **Équipe de genèse MVP** : Composition automatique d'une équipe minimale
## Technologies utilisées
- **Next.js** : Framework React pour la génération statique
- **React** : Bibliothèque JavaScript pour l'interface utilisateur
- **TypeScript** : Typage statique
- **Cytoscape.js** : Visualisation de graphes
- **ECharts** : Visualisation de données (heatmaps, scatter plots)
- **Markdown** : Format des blips et profils
- **YAML** : Métadonnées dans les fichiers Markdown
## Structure du projet
```
TechradarDev/
├── radar-business/ # Contenu du radar business (actif)
│ ├── 2025-01-15/ # Blips organisés par release
│ └── config-business.json # Configuration
├── docs/
│ ├── app/ # Documentation technique
│ └── data/ # Données métier
│ └── team/ # Profils équipe individuels
├── public/ # Fichiers statiques
│ ├── team.html # Page équipe
│ └── team-visualization-data.json # Données équipe
├── scripts/ # Scripts utilitaires
└── Dockerfile.business # Dockerfile pour le déploiement
```
## Commandes principales
```bash
# Développement
npm run serve-business # Démarrer le serveur de développement (port 3006)
# Génération de données
node scripts/generate-team-visualization-data.js # Générer les données équipe
node scripts/extract-technologies.js # Extraire les technologies
node scripts/analyze-business-metrics.js # Analyser les métriques
# Build
npm run build # Build de production
```
## Problèmes courants
Consultez le [guide de dépannage](./troubleshooting.md) pour les problèmes courants :
- Doublons de liens dans la navigation
- Seulement quelques blips affichés
- Page équipe inaccessible
- Données de visualisation manquantes
## Contribution
Pour contribuer au projet :
1. Lire le [guide de contribution](./contribution.md)
2. Créer une branche pour vos modifications
3. Ajouter/modifier les blips dans `radar-business/2025-01-15/`
4. Tester localement avec `npm run serve-business`
5. Créer une pull request
## Support
Pour toute question :
- Consulter la documentation dans `docs/app/`
- Vérifier le [guide de dépannage](./troubleshooting.md)
- Ouvrir une issue sur le dépôt Git
- Contacter l'équipe technique

161
docs/app/architecture.md
View File

@@ -2,23 +2,15 @@
## Vue d'ensemble
Le projet AJR Technology Radar est une application web statique construite avec le framework `aoe_technology_radar`. L'application génère un site web interactif à partir de fichiers Markdown organisés par dates de release.
Le projet AJR Technology Radar est une application web statique construite avec le framework `aoe_technology_radar` (basé sur Next.js). L'application génère un site web interactif à partir de fichiers Markdown organisés par dates de release.
## Structure des répertoires
```
TechradarDev/
├── radar/ # Contenu du radar principal organisé par dates
│ ├── 2017-03-01/ # Release de mars 2017
│ ├── 2018-03-01/ # Release de mars 2018
│ ├── 2019-11-01/ # Release de novembre 2019
│ ├── 2021-07-01/ # Release de juillet 2021
│ ├── 2022-03-28/ # Release de mars 2022
│ ├── 2023-02-23/ # Release de février 2023
│ ├── 2023-11-01/ # Release de novembre 2023
│ ├── 2024-07-10/ # Release de juillet 2024
│ └── 2025-04-10/ # Release d'avril 2025 (actuelle)
├── radar-business/ # Contenu du radar business
├── radar/ # Contenu du radar principal organisé par dates (déprécié)
│ └── 2025-01-15/ # Release de janvier 2025
├── radar-business/ # Contenu du radar business (actif)
│ ├── 2025-01-15/ # Release business de janvier 2025
│ ├── config-business.json # Configuration du radar business
│ ├── FORMAT-BLIP.md # Format des blips business
@@ -28,20 +20,42 @@ TechradarDev/
│ ├── logo.svg # Logo AJR
│ ├── favicon.ico # Icône du site
│ ├── robots.txt # Configuration pour les robots
│ └── strategie-script.js # Script pour les pages de stratégie dynamiques
│ ├── strategie-script.js # Script pour les pages de stratégie dynamiques
│ ├── strategie-link.js # Script alternatif pour les liens stratégie
│ ├── team.html # Page HTML statique pour la visualisation équipe
│ └── team-visualization-data.json # Données JSON pour les visualisations
├── scripts/ # Scripts utilitaires
│ ├── serve-business.sh # Script pour servir le radar business en local
│ ├── start-business.sh # Script de démarrage pour Docker
│ ├── extract-technologies.js # Extraction des technologies depuis la doc
│ └── analyze-business-metrics.js # Analyse des métriques business
│ ├── analyze-business-metrics.js # Analyse des métriques business
│ ├── generate-team-visualization-data.js # Génération des données équipe
│ ├── create-team-page.sh # Script pour créer la page équipe
│ └── patch-navigation.sh # Script pour patcher Navigation.tsx
├── docker/ # Configuration Docker pour le déploiement
│ ├── Dockerfile # Image Docker de production
│ ├── docker-compose.yml # Configuration Docker Compose
│ ├── docker-compose.labels.yml # Labels pour le déploiement
│ └── docker-compose.local.yml # Configuration locale
├── docs/ # Documentation du projet
├── config.json # Configuration principale du radar
├── config.json.backup # Backup de la config (généré par serve-business.sh)
│ ├── app/ # Documentation technique de l'application
│ └── data/ # Données métier et contenu
│ └── team/ # Profils individuels des membres de l'équipe
├── .techradar/ # Framework aoe_technology_radar (généré pendant le build)
│ ├── src/ # Code source Next.js du framework
│ │ ├── pages/ # Pages Next.js (routes)
│ │ │ └── team.tsx # Page /team générée par Dockerfile
│ │ └── components/ # Composants React
│ │ └── Navigation/ # Composant de navigation
│ │ └── Navigation.tsx # Modifié par Dockerfile pour ajouter le lien Équipe
│ ├── data/ # Données du radar
│ │ ├── config.json # Configuration (copiée depuis config-business.json)
│ │ └── radar/ # Blips organisés par release
│ │ └── 2025-01-15/ # Blips de la release actuelle
│ └── public/ # Fichiers statiques servis
│ ├── team.html # Page équipe (copiée depuis public/)
│ └── team-visualization-data.json # Données équipe (copiée depuis public/)
├── config.json # Configuration principale du radar (déprécié)
├── custom.css # Styles personnalisés
├── about.md # Page "À propos" du radar
├── package.json # Dépendances Node.js
@@ -53,6 +67,54 @@ TechradarDev/
└── .drone.yml # Configuration CI/CD Drone
```
## Architecture technique
### Framework de base
Le projet utilise le framework **aoe_technology_radar** qui est basé sur :
- **Next.js** : Framework React pour le rendu côté serveur et la génération statique
- **React** : Bibliothèque JavaScript pour l'interface utilisateur
- **TypeScript** : Typage statique pour JavaScript
### Processus de build
1. **Installation des dépendances** : `npm install` installe `aoe_technology_radar` depuis GitHub
2. **Préparation du framework** : Copie de `node_modules/aoe_technology_radar` vers `.techradar/`
3. **Configuration** : Copie de `radar-business/config-business.json` vers `.techradar/data/config.json`
4. **Données** : Copie des blips depuis `radar-business/2025-01-15/` vers `.techradar/data/radar/2025-01-15/`
5. **Modifications personnalisées** :
- Création de `.techradar/src/pages/team.tsx` (page Next.js pour `/team`)
- Modification de `.techradar/src/components/Navigation/Navigation.tsx` (ajout du lien Équipe)
6. **Build Next.js** : `npm run build:data` puis `npm run build` génère les fichiers statiques
7. **Output** : Fichiers statiques dans `.techradar/out/` servis par un serveur statique
### Modifications personnalisées
Le projet apporte plusieurs modifications au framework de base :
#### 1. Page Équipe (`/team`)
- **Fichier source** : `public/team.html` (HTML statique avec Cytoscape.js et ECharts)
- **Route Next.js** : `.techradar/src/pages/team.tsx` (générée par `Dockerfile.business`)
- **Intégration** : La page Next.js charge `team.html` via un iframe
- **Données** : `public/team-visualization-data.json` généré par `scripts/generate-team-visualization-data.js`
#### 2. Navigation modifiée
- **Fichier modifié** : `.techradar/src/components/Navigation/Navigation.tsx`
- **Modification** : Ajout du lien "👥 Équipe" vers `/team`
- **Méthode** : Script Python dans `Dockerfile.business` qui :
- Supprime tous les liens Équipe existants (évite les doublons)
- Ajoute un seul lien Équipe après le lien "Vue d'ensemble"
#### 3. Scripts JavaScript désactivés
Les scripts suivants ont été désactivés pour éviter les doublons de liens :
- `public/strategie-script.js` : `addLinksToHeader()` désactivée
- `public/strategie-link.js` : `addStrategyLinkToHeader()` désactivée
Tous les liens de navigation sont maintenant gérés uniquement par `Navigation.tsx`.
## Format des fichiers radar
Chaque technologie (blip) est définie dans un fichier Markdown avec un en-tête YAML front matter :
@@ -61,8 +123,17 @@ Chaque technologie (blip) est définie dans un fichier Markdown avec un en-tête
---
title: "Nom de la technologie"
ring: adopt|trial|assess|hold
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
quadrant: technologies-differentiantes|technologies-commodite|technologies-risque|technologies-emergentes
tags: [tag1, tag2]
businessImpact: high|medium|low
costToReplace: 0
revenueImpact: indirect
riskLevel: medium
competencyLevel: beginner
maintenanceCost: 0
differentiation: high
teamCoverage: 1
skillGap: high
---
Description de la technologie en Markdown.
@@ -72,26 +143,29 @@ Description de la technologie en Markdown.
- **title** : Nom de la technologie
- **ring** : Anneau du radar (adopt, trial, assess, hold)
- **quadrant** : Quadrant du radar
- **quadrant** : Quadrant du radar (business)
- **tags** : Tags pour le filtrage (optionnel)
- **Métadonnées business** : Voir [guide-radar-business.md](./guide-radar-business.md)
## Flux de traitement
1. **Lecture des fichiers** : Le framework lit tous les fichiers `.md` dans les dossiers `radar/`
1. **Lecture des fichiers** : Le framework lit tous les fichiers `.md` dans `radar-business/2025-01-15/`
2. **Parsing** : Extraction des métadonnées YAML et du contenu Markdown
3. **Génération** : Création d'une application React statique
4. **Build** : Compilation en fichiers HTML/CSS/JS statiques
5. **Serve** : Service via un serveur web statique
5. **Serve** : Service via un serveur web statique (`serve` package)
## Dépendances principales
- **aoe_technology_radar** : Framework principal (dépendance GitHub)
- **Node.js** : Runtime JavaScript (version 20+)
- **npm** : Gestionnaire de paquets
- **gray-matter** : Parsing YAML front matter
- **postcss** : Traitement CSS
## Configuration
La configuration principale se trouve dans `config.json` et définit :
La configuration principale se trouve dans `radar-business/config-business.json` et définit :
- Les quadrants et leurs descriptions
- Les anneaux (rings) et leurs significations
- Les couleurs et le style
@@ -111,24 +185,28 @@ Le Radar Technologique Laplank est un tech radar classique avec :
- **Pages de stratégie** : Pages dynamiques générées via `public/strategie-script.js`
- **Protection par mot de passe** : Authentification client-side (mot de passe : `laplank-radar`)
- **Base path** : `/` (racine, pas de sous-chemin)
- **Page Équipe** : `/team` avec visualisations interactives
### Scripts de stratégie
Le fichier `public/strategie-script.js` contient :
- La logique de protection par mot de passe
- La conversion Markdown vers HTML pour les pages de stratégie
- La gestion de la navigation dans le header
- Le contenu des trois pages de stratégie :
- Stratégie d'Évolution Technique
- Stratégie Business
- Opportunités DataViz Expert
**Note** : Les fonctions d'ajout de liens dans le header ont été désactivées pour éviter les doublons. Tous les liens sont maintenant gérés par `Navigation.tsx`.
## Build et déploiement
Le projet utilise plusieurs commandes :
- `npm run build` : Génère les fichiers statiques du radar principal
- `npm run serve` : Lance un serveur de développement du radar principal (port 3000)
- `npm run serve-business` : Lance un serveur de développement du radar business (port 3006)
- `npm run extract-tech` : Extrait les technologies depuis la documentation
- `npm run analyze-business` : Analyse les métriques business
Le déploiement se fait via Docker avec plusieurs configurations selon l'environnement :
- **Radar principal** : Via `docker/Dockerfile` ou `Dockerfile`
@@ -136,3 +214,42 @@ Le déploiement se fait via Docker avec plusieurs configurations selon l'environ
Voir [deploiement.md](./deploiement.md) pour plus de détails.
## Génération des données équipe
Le script `scripts/generate-team-visualization-data.js` :
- Lit les profils d'équipe depuis `docs/data/team/*.md`
- Lit les technologies depuis `radar-business/2025-01-15/*.md`
- Génère `public/team-visualization-data.json` avec :
- Données réseau (nodes/edges) pour Cytoscape.js
- Matrice de congestion pour ECharts
- Équipe de genèse MVP avec statistiques
Ce fichier est utilisé par `public/team.html` pour les visualisations interactives.
## Structure des profils équipe
Les profils d'équipe sont stockés dans `docs/data/team/*.md` avec le format suivant :
```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"
softSkills:
- "Autonomie"
projects:
- "Projet1"
---
```
Voir [guide-page-equipe.md](./guide-page-equipe.md) pour plus de détails.

75
docs/app/configuration.md
View File

@@ -1,8 +1,8 @@
# Configuration
## Fichier config.json
## Fichier config-business.json
Le fichier `config.json` contient toute la configuration du radar. Il définit l'apparence, le comportement et la structure du radar.
Le fichier `radar-business/config-business.json` contient toute la configuration du Radar Technologique Laplank. Il définit l'apparence, le comportement et la structure du radar.
## Structure de configuration
@@ -12,9 +12,9 @@ Le fichier `config.json` contient toute la configuration du radar. Il définit l
{
"basePath": "",
"baseUrl": "",
"editUrl": "https://git.open.us.org/syoul/TechradarDev/_edit/main/radar/{release}/{id}.md",
"editUrl": "https://git.open.us.org/syoul/TechradarDev/_edit/main/radar-business/{release}/{id}.md",
"logoFile": "logo.svg",
"jsFile": "strategie-script.js"
"jsFile": "/strategie-script.js"
}
```
@@ -22,7 +22,7 @@ Le fichier `config.json` contient toute la configuration du radar. Il définit l
- **baseUrl** : URL de base du site
- **editUrl** : Template d'URL pour éditer les fichiers (utilise {release} et {id})
- **logoFile** : Nom du fichier logo dans `public/`
- **jsFile** : Fichier JavaScript personnalisé à charger (optionnel, utilisé pour le radar business)
- **jsFile** : Fichier JavaScript personnalisé à charger (`/strategie-script.js` pour le radar business)
### Options d'affichage (toggles)
@@ -58,57 +58,59 @@ Définit l'ordre des sections dans l'interface.
{
"colors": {
"foreground": "#fff",
"background": "#173d7a",
"highlight": "#029df7",
"background": "#1a4d3a",
"highlight": "#2ecc71",
"content": "#fff",
"text": "#575757",
"link": "#029df7",
"link": "#2ecc71",
"border": "rgba(255, 255, 255, 0.1)",
"tag": "rgba(255, 255, 255, 0.1)"
}
}
```
Personnalisation des couleurs de l'interface.
Personnalisation des couleurs de l'interface avec un thème vert.
### Quadrants
### Quadrants Business
Les quadrants définissent les quatre catégories principales :
Les quadrants définissent les quatre catégories principales selon l'impact business :
1. **Languages & Frameworks** : Langages et frameworks de développement
2. **Methods & Patterns** : Méthodes et patterns de développement
3. **Platforms & Operations** : Plateformes et opérations
4. **Tools** : Outils de développement
1. **Technologies Différenciantes** : Créent un avantage concurrentiel et de la valeur différenciante
2. **Technologies de Commodité** : Nécessaires mais non différenciantes, à optimiser pour réduire les coûts
3. **Technologies à Risque** : Obsolètes, coûteuses ou présentant des risques, à migrer ou remplacer
4. **Technologies Émergentes** : Opportunités futures, à évaluer et potentiellement adopter
Chaque quadrant a :
- **id** : Identifiant unique
- **id** : Identifiant unique (technologies-differentiantes, technologies-commodite, technologies-risque, technologies-emergentes)
- **title** : Titre affiché
- **description** : Description du quadrant
- **color** : Couleur associée
### Anneaux (Rings)
Les anneaux classifient les technologies selon leur niveau d'adoption :
Les anneaux classifient les technologies selon leur niveau d'adoption. Le Radar Technologique Laplank utilise les anneaux classiques :
1. **Adopt** : Recommandé, utilisé avec succès
2. **Trial** : À essayer, prometteur
3. **Assess** : À évaluer, à surveiller
4. **Hold** : À éviter, à remplacer
1. **Adopt** : Technologies recommandées et utilisées avec succès en production. Stables, éprouvées, peuvent être adoptées en toute confiance pour de nouveaux projets.
2. **Trial** : Technologies à essayer. Prometteuses et testées avec succès dans certains contextes. À considérer pour de nouveaux projets.
3. **Assess** : Technologies à évaluer. Prometteuses mais nécessitent une évaluation approfondie avant adoption. À surveiller et tester.
4. **Hold** : Technologies à éviter ou à remplacer. Présentent des risques, sont obsolètes ou ne sont plus recommandées. À éviter pour de nouveaux projets.
Chaque anneau a :
- **id** : Identifiant unique
- **id** : Identifiant unique (adopt, trial, assess, hold)
- **title** : Titre affiché
- **description** : Description de l'anneau
- **color** : Couleur associée
- **radius** : Rayon dans le graphique (0-1)
- **strokeWidth** : Épaisseur du trait
**Important** : Tous les blips doivent utiliser ces rings (adopt|trial|assess|hold). Les anciens rings (core, strategic, support) ne sont plus utilisés.
### Flags (Drapeaux)
Les flags marquent les changements entre versions :
- **new** : Nouveau dans cette version
- **changed** : Modifié récemment
- **new** : Nouveau dans cette version (couleur : #f1235a)
- **changed** : Modifié récemment (couleur : #40a7d1)
- **default** : Inchangé
### Graphique
@@ -128,7 +130,7 @@ Les flags marquent les changements entre versions :
### Labels (Textes)
Les labels permettent de personnaliser tous les textes de l'interface, notamment :
- Titre du site
- Titre du site : "Radar Technologique Laplank"
- Textes des pages
- Messages d'erreur
- Placeholders
@@ -138,7 +140,7 @@ Les labels permettent de personnaliser tous les textes de l'interface, notamment
### Modifier les couleurs
Éditez la section `colors` dans `config.json` avec les codes hexadécimaux souhaités.
Éditez la section `colors` dans `radar-business/config-business.json` avec les codes hexadécimaux souhaités.
### Ajouter un quadrant
@@ -146,7 +148,7 @@ Ajoutez un nouvel objet dans le tableau `quadrants` avec les propriétés requis
### Modifier les descriptions
Les descriptions des quadrants et anneaux peuvent être modifiées directement dans `config.json`.
Les descriptions des quadrants et anneaux peuvent être modifiées directement dans `config-business.json`.
### Styles personnalisés
@@ -159,7 +161,7 @@ Le Radar Technologique Laplank utilise une configuration spécifique dans `radar
### Différences principales
- **basePath** : `""` (vide) pour servir à la racine
- **jsFile** : `"strategie-script.js"` pour charger le script de stratégie
- **jsFile** : `"/strategie-script.js"` pour charger le script de stratégie
- **Quadrants business** : Technologies Différenciantes, Commodité, Risque, Émergentes
- **Anneaux classiques** : Hold, Assess, Trial, Adopt
- **Couleurs** : Thème vert (`#1a4d3a` pour le background, `#2ecc71` pour les accents)
@@ -169,7 +171,8 @@ Le Radar Technologique Laplank utilise une configuration spécifique dans `radar
Le fichier `public/strategie-script.js` est chargé automatiquement et fournit :
- Protection par mot de passe (authentification client-side)
- Pages de stratégie dynamiques (Markdown converti en HTML)
- Navigation dans le header
**Note** : Les fonctions d'ajout de liens dans le header ont été désactivées pour éviter les doublons. Tous les liens sont maintenant gérés par `Navigation.tsx`.
## Variables d'environnement
@@ -191,6 +194,20 @@ Les tags suivants sont établis pour classifier les technologies :
- ci/cd
- ux/ui
- documentation
- blockchain
- infrastructure
- dataviz
- mobile
Les tags sont utilisés dans les fichiers Markdown des blips et permettent le filtrage dans l'interface.
## Migration des rings
Si vous avez des blips avec les anciens rings (core, strategic, support), ils doivent être migrés vers les rings standards :
- **core** → **adopt** (technologies fondamentales en production)
- **strategic** → **assess** (technologies prometteuses à évaluer)
- **support** → **adopt** (technologies utilisées en production)
- **trial** → **trial** (déjà correct)
Le script `scripts/migrate-rings.sh` peut être utilisé pour automatiser cette migration.

160
docs/app/contribution.md
View File

@@ -2,7 +2,7 @@
## Vue d'ensemble
Ce guide explique comment contribuer au Technology Radar AJR en ajoutant, modifiant ou supprimant des technologies (blips).
Ce guide explique comment contribuer au Technology Radar AJR en ajoutant, modifiant ou supprimant des technologies (blips) et des profils équipe.
## Processus de contribution
@@ -22,36 +22,59 @@ git checkout -b feature/nom-de-la-technologie
1. Créer un fichier Markdown dans le dossier de release approprié :
```
radar/2025-04-10/nom-technologie.md
radar-business/2025-01-15/nom-technologie.md
```
2. Utiliser le format standard :
2. Utiliser le format standard avec toutes les métadonnées :
```markdown
---
title: "Nom de la technologie"
ring: adopt|trial|assess|hold
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
quadrant: technologies-differentiantes|technologies-commodite|technologies-risque|technologies-emergentes
tags: [tag1, tag2]
businessImpact: high|medium|low
costToReplace: 0
revenueImpact: indirect
riskLevel: medium
competencyLevel: beginner
maintenanceCost: 0
differentiation: high
teamCoverage: 1
skillGap: high
---
Description de la technologie.
## Avantages
## Impact Business
- Point 1
- Point 2
Description de l'impact sur le business.
## Cas d'usage AJR
## Coûts
Description de l'utilisation chez AJR.
- Coût de remplacement : 0€
- Coût de maintenance annuel : 0€
## Compétences
- Nombre de personnes maîtrisant : 1
- Membres de l'équipe : pseudo
- Niveau moyen : beginner
- Risque de compétence manquante : high
## Recommandations
Recommandations stratégiques pour cette technologie.
```
Voir `radar-business/FORMAT-BLIP.md` pour le format complet.
#### Modifier un blip existant
1. Localiser le fichier dans le dossier de release
1. Localiser le fichier dans `radar-business/2025-01-15/`
2. Modifier le contenu ou les métadonnées
3. Si vous changez le ring ou le quadrant, documenter la raison
4. **Important** : Vérifier que le ring est standard (adopt, trial, assess, hold)
#### Supprimer un blip
@@ -59,10 +82,48 @@ Si une technologie doit être retirée du radar :
- La déplacer vers le ring "hold" plutôt que de la supprimer
- Ou la supprimer complètement si elle n'est plus pertinente
### 4. Tester localement
### 4. Ajouter ou modifier un profil équipe
#### Ajouter un profil équipe
1. Créer un fichier Markdown dans `docs/data/team/` :
```
docs/data/team/pseudo.md
```
2. Utiliser le format standard :
```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"
softSkills:
- "Autonomie"
projects:
- "Projet1"
---
```
3. Régénérer les données équipe :
```bash
node scripts/generate-team-visualization-data.js
```
### 5. Tester localement
```bash
npm run serve
npm run serve-business
```
Vérifier :
@@ -70,15 +131,18 @@ Vérifier :
- Le positionnement dans le bon quadrant et ring
- La lisibilité du contenu
- Le fonctionnement des tags
- La page équipe (`/team`) affiche correctement les données
### 5. Commiter les changements
### 6. Commiter les changements
```bash
git add radar/2025-04-10/nom-technologie.md
git add radar-business/2025-01-15/nom-technologie.md
git add docs/data/team/pseudo.md
git add public/team-visualization-data.json
git commit -m "feat: ajouter [technologie] au quadrant [quadrant]"
```
### 6. Pousser et créer une pull request
### 7. Pousser et créer une pull request
```bash
git push origin feature/nom-de-la-technologie
@@ -90,17 +154,19 @@ Créer une pull request sur le dépôt Git.
### Choix du ring
- **Adopt** : Technologie utilisée avec succès dans plusieurs projets, stable et recommandée
- **Trial** : Technologie testée avec succès, à considérer pour de nouveaux projets
- **Assess** : Technologie prometteuse, à évaluer selon les besoins
- **Hold** : Technologie à éviter ou à remplacer, mais peut être maintenue dans les projets existants
- **Adopt** : Technologies recommandées et utilisées avec succès en production. Stables, éprouvées, peuvent être adoptées en toute confiance pour de nouveaux projets.
- **Trial** : Technologies à essayer. Prometteuses et testées avec succès dans certains contextes. À considérer pour de nouveaux projets.
- **Assess** : Technologies à évaluer. Prometteuses mais nécessitent une évaluation approfondie avant adoption. À surveiller et tester.
- **Hold** : Technologies à éviter ou à remplacer. Présentent des risques, sont obsolètes ou ne sont plus recommandées. À éviter pour de nouveaux projets.
**Important** : Les anciens rings (core, strategic, support, legacy) ne sont plus utilisés. Tous les blips doivent utiliser les rings standards (adopt, trial, assess, hold).
### Choix du quadrant
- **Languages & Frameworks** : Langages de programmation et frameworks de développement
- **Methods & Patterns** : Méthodologies, patterns architecturaux, pratiques de développement
- **Platforms & Operations** : Plateformes cloud, infrastructure, services opérationnels
- **Tools** : Outils de développement, utilitaires, logiciels
- **Technologies Différenciantes** : Créent un avantage concurrentiel et de la valeur différenciante
- **Technologies de Commodité** : Nécessaires mais non différenciantes, à optimiser pour réduire les coûts
- **Technologies à Risque** : Obsolètes, coûteuses, à migrer ou remplacer
- **Technologies Émergentes** : Opportunités futures, à évaluer et potentiellement adopter
### Tags
@@ -115,15 +181,20 @@ Utiliser les tags établis :
- ci/cd
- ux/ui
- documentation
- blockchain
- infrastructure
- dataviz
- mobile
Ajouter plusieurs tags si la technologie couvre plusieurs domaines.
### Qualité du contenu
- **Clarté** : Description claire et concise
- **Pertinence** : Focus sur l'utilisation chez AJR
- **Pertinence** : Focus sur l'utilisation dans l'écosystème Duniter/Ğ1
- **Objectivité** : Présenter les avantages et inconvénients
- **Concision** : Rester factuel et éviter les détails superflus
- **Métadonnées complètes** : Remplir toutes les métadonnées business
## Format des commits
@@ -134,6 +205,8 @@ feat: ajouter [technologie] au quadrant [quadrant]
fix: corriger la description de [technologie]
update: déplacer [technologie] de trial à adopt
docs: améliorer la documentation de [technologie]
feat(team): ajouter profil [pseudo]
fix(team): mettre à jour compétences de [pseudo]
```
## Créer une nouvelle release
@@ -148,25 +221,41 @@ Quand créer une nouvelle release :
1. Créer un nouveau dossier avec la date :
```bash
mkdir radar/2025-07-15
mkdir radar-business/2025-07-15
```
2. Copier les blips pertinents depuis la release précédente
3. Ajouter les nouveaux blips
4. Mettre à jour les blips existants si nécessaire
4. Mettre à jour les blips existants si nécessaire (changement de ring, quadrant, description)
5. Documenter les changements majeurs
5. **Migrer les rings si nécessaire** : S'assurer que tous les blips utilisent les rings standards
6. Documenter les changements majeurs
## Migration des rings
Si vous avez des blips avec les anciens rings, utilisez ce mapping :
- **core** → **adopt** : Technologies fondamentales en production
- **strategic** → **assess** : Technologies prometteuses à évaluer
- **support** → **adopt** : Technologies utilisées en production
- **trial** → **trial** : Déjà correct
- **legacy** → **hold** : Technologies obsolètes à remplacer
Le script `scripts/migrate-rings.sh` peut être utilisé pour automatiser cette migration.
## Review process
Les contributions sont revues pour :
- **Exactitude** : Les informations sont correctes
- **Pertinence** : La technologie est pertinente pour AJR
- **Pertinence** : La technologie est pertinente pour l'écosystème
- **Format** : Le format Markdown est correct
- **Classification** : Le ring et quadrant sont appropriés
- **Rings standards** : Utilisation des rings standards (adopt, trial, assess, hold)
- **Métadonnées** : Toutes les métadonnées business sont remplies
- **Qualité** : Le contenu est clair et utile
## Questions fréquentes
@@ -177,7 +266,7 @@ Non. Le radar ne contient que des technologies testées au moins une fois par l'
### Comment décider entre deux quadrants ?
Choisir le quadrant le plus approprié. Si c'est ambigu, discuter avec l'équipe.
Choisir le quadrant le plus approprié selon l'impact business. Si c'est ambigu, discuter avec l'équipe.
### Puis-je modifier un blip d'une release précédente ?
@@ -187,14 +276,25 @@ Généralement non. Les releases précédentes sont figées. Créer un nouveau b
Les déplacer vers le ring "hold" avec une explication de pourquoi elles ne sont plus recommandées.
### Quels rings dois-je utiliser ?
Toujours utiliser les rings standards : **adopt**, **trial**, **assess**, **hold**. Les anciens rings (core, strategic, support, legacy) ne sont plus utilisés.
### Comment mettre à jour les données é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)
## Ressources
- [Guide de développement](./developpement.md)
- [Configuration](./configuration.md)
- [Architecture](./architecture.md)
- [Format des blips](../radar-business/FORMAT-BLIP.md)
- [Guide page équipe](./guide-page-equipe.md)
- Framework source : https://github.com/AOEpeople/aoe_technology_radar
## Contact
Pour toute question sur les contributions, contacter l'équipe AJR ou ouvrir une issue sur le dépôt Git.

201
docs/app/deploiement.md
View File

@@ -63,49 +63,6 @@ L'application sera accessible sur le port 3000.
Le script `docker-entrypoint.sh` modifie dynamiquement le `basePath` dans `config.json` au démarrage du conteneur en utilisant la variable d'environnement `BASE_PATH`.
## Déploiement statique
### Build des fichiers statiques
```bash
npm install
npm run build
```
Les fichiers sont générés dans le répertoire `build/`.
### Servir avec un serveur web
#### Nginx
```nginx
server {
listen 80;
server_name coeurbox.syoul.fr;
root /chemin/vers/build;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
```
#### Apache
```apache
<VirtualHost *:80>
ServerName coeurbox.syoul.fr
DocumentRoot /chemin/vers/build
<Directory /chemin/vers/build>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
```
## Déploiement du Radar Technologique Laplank avec Portainer
Le Radar Technologique Laplank est déployé via Portainer en utilisant une stack Docker Compose.
@@ -137,15 +94,52 @@ Le fichier `docker-compose.business.yml` configure :
### Dockerfile Business
Le `Dockerfile.business` :
- Utilise Node.js 20 Alpine
- Configure les variables d'environnement pour désactiver Husky
- Installe les dépendances avec `--ignore-scripts`
- Patche le package `aoe_technology_radar` pour inclure `gray-matter`
- Pré-installe `.techradar` pendant le build
- Applique la configuration business (`config-business.json`)
- Expose le port 3000
- Démarre via `scripts/start-business.sh`
Le `Dockerfile.business` effectue les opérations suivantes :
1. **Installation des dépendances** :
- Node.js 20 Alpine
- Git et Python3 pour les scripts
- Variables d'environnement pour désactiver Husky
2. **Préparation du framework** :
- Copie de `node_modules/aoe_technology_radar` vers `.techradar/`
- Patch du package pour inclure `gray-matter` et `postcss`
3. **Configuration des données** :
- Purge des données de démo : `rm -rf .techradar/data/radar/*`
- Copie des blips business : `radar-business/2025-01-15/*` → `.techradar/data/radar/2025-01-15/`
- Copie de la config : `radar-business/config-business.json` → `.techradar/data/config.json`
4. **Modifications personnalisées** :
- Création de `.techradar/src/pages/team.tsx` (page Next.js pour `/team`)
- Modification de `.techradar/src/components/Navigation/Navigation.tsx` via script Python :
- Suppression de tous les liens Équipe existants (évite les doublons)
- Ajout d'un seul lien "👥 Équipe" après le lien "Vue d'ensemble"
5. **Build Next.js** :
- `npm run build:data` : Génère les données du radar
- `npm run build` : Build de l'application Next.js
6. **Copie des fichiers publics** :
- Copie de `public/team.html` et `public/team-visualization-data.json` vers `.techradar/public/`
- Les fichiers sont ensuite copiés dans `out/` après le build
7. **Démarrage** :
- Exécution de `scripts/start-business.sh` qui :
- Vérifie que `team.html` et `team-visualization-data.json` sont dans `out/`
- Les copie depuis `public/` si nécessaire
- Démarre le serveur statique `serve` sur le port 3000
### Script Python pour Navigation.tsx
Le script `/tmp/add_team_link.py` dans le Dockerfile :
1. **Vérifie l'existence du fichier** : `.techradar/src/components/Navigation/Navigation.tsx`
2. **Supprime tous les liens Équipe existants** : Évite les doublons même si le script s'exécute plusieurs fois
3. **Ajoute un seul lien Équipe** : Après le lien "Vue d'ensemble"
4. **Vérifie le résultat** : S'assure qu'il n'y a qu'un seul lien après l'opération
Le script shell `/tmp/add_team_link.sh` orchestre l'exécution et vérifie le résultat.
### Authentification Git pour Portainer
@@ -190,19 +184,58 @@ Pour mettre à jour le Radar Technologique Laplank dans Portainer :
6. Cliquer sur **Editor** → **Update the stack**
7. L'image sera reconstruite depuis zéro
**Option 4 : Utiliser le CACHE_BUST automatique**
Le `docker-compose.business.yml` inclut maintenant un `CACHE_BUST` avec timestamp qui change automatiquement. Cependant, Portainer peut ne pas interpréter les variables shell `$(date +%s)`. Dans ce cas :
1. Utiliser l'**Option 1** avec `--no-cache`
2. Ou modifier manuellement le `CACHE_BUST` dans le compose avant de mettre à jour
**Vérification après mise à jour :**
- Vérifier les logs : **Containers** → `laplank-radar-technolologique` → **Logs**
- Tester l'application : `http://<votre-serveur>:3006`
- Vérifier que les changements sont visibles (par exemple, le contenu de `about.md` ou `custom.css`)
- Vérifier qu'il n'y a qu'un seul lien "Équipe" dans la navigation
**Pourquoi le cache pose problème ?**
Docker utilise un système de cache par couches. Si les fichiers copiés n'ont pas changé selon l'algorithme de détection de Docker, il réutilise les couches en cache. C'est pourquoi il faut forcer un rebuild complet avec `--no-cache` pour garantir que tous les fichiers sont bien copiés et que l'application est reconstruite avec les dernières modifications.
## Déploiement statique
### Build des fichiers statiques
```bash
npm install
npm run build
```
Les fichiers sont générés dans le répertoire `build/`.
### Servir avec un serveur web
#### Nginx
```nginx
server {
listen 80;
server_name coeurbox.syoul.fr;
root /chemin/vers/build;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
```
#### Apache
```apache
<VirtualHost *:80>
ServerName coeurbox.syoul.fr
DocumentRoot /chemin/vers/build
<Directory /chemin/vers/build>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
```
## Déploiement avec Drone CI
Le projet est configuré pour le déploiement automatique via Drone CI (`.drone.yml`).
@@ -262,22 +295,32 @@ Le projet est configuré pour fonctionner derrière un reverse proxy (Traefik) v
- Configurer les headers de sécurité appropriés
- Limiter l'accès si nécessaire
- Surveiller les logs
- Le Radar Business est protégé par un mot de passe client-side
## Mise à jour
### Mettre à jour le contenu
1. Modifier les fichiers dans `radar/`
1. Modifier les fichiers dans `radar-business/2025-01-15/`
2. Rebuild l'image :
```bash
docker compose build
docker compose build --no-cache
docker compose up -d
```
### Mettre à jour les dépendances
1. Modifier `package.json` si nécessaire
2. Rebuild l'image complète
2. Rebuild l'image complète avec `--no-cache`
### Mettre à jour les profils équipe
1. Modifier les fichiers dans `docs/data/team/*.md`
2. Régénérer les données :
```bash
node scripts/generate-team-visualization-data.js
```
3. Rebuild l'image Docker
## Monitoring
@@ -307,6 +350,21 @@ curl http://localhost:3006/
Note : Le Radar Technologique Laplank est protégé par un mot de passe, donc la réponse peut être l'écran d'authentification.
### Vérifications post-déploiement
1. **Vérifier la navigation** :
- Le lien "👥 Équipe" doit apparaître une seule fois
- Tous les liens doivent fonctionner
2. **Vérifier les données** :
- Tous les blips doivent être affichés (38 blips)
- Les rings doivent être corrects (adopt, trial, assess, hold)
3. **Vérifier la page équipe** :
- `/team` doit être accessible
- Les visualisations doivent se charger
- Les données doivent être présentes
## Rollback
En cas de problème, revenir à une version précédente :
@@ -319,29 +377,10 @@ docker compose down
git checkout <commit-hash>
# Rebuild et redémarrer
docker compose build
docker compose build --no-cache
docker compose up -d
```
## Troubleshooting
### Problème de basePath
Si l'application ne se charge pas correctement :
- Vérifier la variable `BASE_PATH`
- Vérifier les logs du conteneur
- Vérifier la configuration du reverse proxy
### Problème de permissions
Si des erreurs de permissions apparaissent :
- Vérifier les UID/GID dans le Dockerfile
- Vérifier les permissions des volumes montés
### Problème de build
Si le build échoue :
- Vérifier la version de Node.js
- Vérifier les dépendances npm
- Nettoyer le cache : `docker system prune -a`
Voir [troubleshooting.md](./troubleshooting.md) pour les problèmes courants et leurs solutions.

230
docs/app/developpement.md
View File

@@ -5,6 +5,7 @@
- **Node.js** : Version 20 ou supérieure
- **npm** : Gestionnaire de paquets Node.js
- **Git** : Pour cloner et gérer le dépôt
- **Python 3** : Pour les scripts de modification (optionnel, utilisé dans Docker)
## Installation
@@ -65,7 +66,7 @@ Les fichiers générés sont créés dans le répertoire `build/` (généré par
1. Créer un nouveau fichier Markdown dans le dossier de release approprié :
```
radar/2025-04-10/nom-technologie.md
radar-business/2025-01-15/nom-technologie.md
```
2. Utiliser le format suivant :
@@ -74,69 +75,162 @@ Les fichiers générés sont créés dans le répertoire `build/` (généré par
---
title: "Nom de la technologie"
ring: adopt|trial|assess|hold
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
quadrant: technologies-differentiantes|technologies-commodite|technologies-risque|technologies-emergentes
tags: [tag1, tag2]
businessImpact: high|medium|low
costToReplace: 0
revenueImpact: indirect
riskLevel: medium
competencyLevel: beginner
maintenanceCost: 0
differentiation: high
teamCoverage: 1
skillGap: high
---
Description de la technologie en Markdown.
## Avantages
## Impact Business
- Point 1
- Point 2
Description de l'impact sur le business.
## Cas d'usage
## Coûts
Description des cas d'usage chez AJR.
- Coût de remplacement : 0€
- Coût de maintenance annuel : 0€
## Compétences
- Nombre de personnes maîtrisant : 1
- Membres de l'équipe : pseudo
- Niveau moyen : beginner
- Risque de compétence manquante : high
## Recommandations
Recommandations stratégiques pour cette technologie.
```
### Format des métadonnées
- **title** (obligatoire) : Nom de la technologie
- **ring** (obligatoire) : `adopt`, `trial`, `assess`, ou `hold`
- **quadrant** (obligatoire) : Un des quatre quadrants définis dans `config.json`
- **ring** (obligatoire) : `adopt`, `trial`, `assess`, ou `hold` (voir [configuration.md](./configuration.md))
- **quadrant** (obligatoire) : Un des quatre quadrants définis dans `radar-business/config-business.json`
- **tags** (optionnel) : Tableau de tags pour le filtrage
- **Métadonnées business** : Voir `radar-business/FORMAT-BLIP.md` pour la liste complète
**Important** : Tous les blips doivent utiliser les rings standards (adopt, trial, assess, hold). Les anciens rings (core, strategic, support) ne sont plus utilisés.
### Exemple complet
```markdown
---
title: "Docker"
ring: trial
quadrant: tools
tags: [devops, ci/cd]
ring: adopt
quadrant: technologies-commodite
tags: [devops, ci/cd, infrastructure]
businessImpact: medium
costToReplace: 0
revenueImpact: indirect
riskLevel: low
competencyLevel: intermediate
maintenanceCost: 5000
differentiation: low
teamCoverage: 3
skillGap: low
---
Docker est une plateforme de conteneurisation qui permet de packager des applications avec leurs dépendances.
## Avantages
## Impact Business
- Isolation des environnements
- Portabilité entre environnements
- Facilite le déploiement
Technologie essentielle pour le déploiement et la gestion des environnements.
## Utilisation chez AJR
## Coûts
Nous utilisons Docker pour containeriser nos applications et faciliter le déploiement.
- Coût de remplacement : 0€ (pas de remplacement prévu)
- Coût de maintenance annuel : 5 000€ (licences, support)
## Compétences
- Nombre de personnes maîtrisant : 3
- Membres de l'équipe : pseudo1, pseudo2, pseudo3
- Niveau moyen : intermediate
- Risque de compétence manquante : low
## Recommandations
Continuer à utiliser Docker pour tous les nouveaux projets. Standardiser les pratiques de conteneurisation.
```
## Modifier un blip existant
1. Localiser le fichier dans le dossier de release approprié
1. Localiser le fichier dans `radar-business/2025-01-15/`
2. Modifier le contenu Markdown
3. Si nécessaire, modifier les métadonnées (ring, quadrant, tags)
4. Tester localement avec `npm run serve`
4. Tester localement avec `npm run serve-business`
## Créer une nouvelle release
1. Créer un nouveau dossier avec la date au format `YYYY-MM-DD` :
```bash
mkdir radar/2025-07-15
mkdir radar-business/2025-07-15
```
2. Copier les blips pertinents depuis la release précédente ou créer de nouveaux blips
3. Mettre à jour les blips existants si nécessaire
3. Mettre à jour les blips existants si nécessaire (changement de ring, quadrant, description)
## Gestion des profils équipe
### Créer un profil équipe
1. Créer un fichier Markdown dans `docs/data/team/` :
```
docs/data/team/pseudo.md
```
2. Utiliser le format suivant :
```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.
```
### Générer les données de visualisation
Après avoir modifié les profils équipe ou les technologies, régénérer les données :
```bash
node scripts/generate-team-visualization-data.js
```
Ce script génère `public/team-visualization-data.json` utilisé par la page `/team`.
## Ajouter des images
@@ -151,29 +245,71 @@ Nous utilisons Docker pour containeriser nos applications et faciliter le déplo
Le fichier `custom.css` permet d'ajouter des styles personnalisés. Les styles sont appliqués globalement à l'application.
## Scripts disponibles
### Extraction des technologies
```bash
npm run extract-tech
# ou
node scripts/extract-technologies.js
```
Extrait les technologies depuis `docs/data/technologies-duniter.md` et génère les blips dans `radar-business/2025-01-15/`.
### Analyse des métriques business
```bash
npm run analyze-business
# ou
node scripts/analyze-business-metrics.js
```
Analyse les métriques business et génère un rapport dans `docs/data/analyse-strategique.md`.
### Génération des données équipe
```bash
node scripts/generate-team-visualization-data.js
```
Génère `public/team-visualization-data.json` à partir des profils équipe et des technologies.
## Débogage
### Vérifier les erreurs de format
Le framework valide les fichiers Markdown. En cas d'erreur :
- Vérifier la syntaxe YAML front matter
- Vérifier que les valeurs de `ring` et `quadrant` correspondent aux valeurs définies dans `config.json`
- Vérifier que les valeurs de `ring` et `quadrant` correspondent aux valeurs définies dans `radar-business/config-business.json`
- Vérifier la syntaxe Markdown
### Problèmes courants
1. **Erreur de parsing YAML** : Vérifier les guillemets et l'indentation
2. **Blip non affiché** : Vérifier que le quadrant et le ring sont corrects
2. **Blip non affiché** : Vérifier que le quadrant et le ring sont corrects (adopt, trial, assess, hold)
3. **Images non chargées** : Vérifier le chemin relatif depuis `public/`
4. **Rings invalides** : Vérifier que tous les blips utilisent les rings standards
### Vérifier les rings utilisés
```bash
cd radar-business/2025-01-15
grep -h "^ring:" *.md | sort | uniq -c
```
Doit retourner uniquement : adopt, trial, assess, hold
## Workflow recommandé
1. Créer une branche Git pour vos modifications
2. Ajouter/modifier les fichiers radar
3. Tester localement avec `npm run serve`
4. Vérifier l'affichage et le formatage
5. Commiter et pousser les changements
6. Créer une pull request si applicable
2. Ajouter/modifier les fichiers radar dans `radar-business/2025-01-15/`
3. Modifier les profils équipe dans `docs/data/team/` si nécessaire
4. Régénérer les données équipe : `node scripts/generate-team-visualization-data.js`
5. Tester localement avec `npm run serve-business`
6. Vérifier l'affichage et le formatage
7. Commiter et pousser les changements
8. Créer une pull request si applicable
## Commandes utiles
@@ -181,12 +317,21 @@ Le framework valide les fichiers Markdown. En cas d'erreur :
# Installer les dépendances
npm install
# Démarrer le serveur de développement
npm run serve
# Démarrer le serveur de développement (business)
npm run serve-business
# Build de production
npm run build
# Extraire les technologies
npm run extract-tech
# Analyser les métriques
npm run analyze-business
# Générer les données équipe
node scripts/generate-team-visualization-data.js
# Vérifier les fichiers modifiés
git status
@@ -203,3 +348,26 @@ Les builds automatiques :
- Déploient sur l'environnement de test
- Envoient des notifications Telegram
## Tests locaux avant déploiement
Avant de déployer, vérifier :
1. **Tous les blips utilisent les rings standards** :
```bash
cd radar-business/2025-01-15
grep -h "^ring:" *.md | sort | uniq
```
2. **Les données équipe sont à jour** :
```bash
node scripts/generate-team-visualization-data.js
```
3. **La page équipe fonctionne** :
- Démarrer `npm run serve-business`
- Accéder à http://localhost:3006/team
- Vérifier que les visualisations se chargent
4. **La navigation est correcte** :
- Vérifier qu'il n'y a qu'un seul lien "Équipe"
- Vérifier que tous les liens fonctionnent

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/

49
docs/app/guide-radar-business.md
View File

@@ -25,11 +25,13 @@ Le radar est organisé en 4 quadrants business :
Chaque technologie est classée dans un des 4 anneaux classiques :
1. **Adopt** : Technologies recommandées et utilisées avec succès. Stables et éprouvées, peuvent être adoptées en toute confiance pour de nouveaux projets.
1. **Adopt** : Technologies recommandées et utilisées avec succès en production. Stables, éprouvées, peuvent être adoptées en toute confiance pour de nouveaux projets.
2. **Trial** : Technologies à essayer. Prometteuses et testées avec succès dans certains contextes. À considérer pour de nouveaux projets.
3. **Assess** : Technologies à évaluer. Prometteuses mais nécessitent une évaluation approfondie avant adoption. À surveiller et tester.
4. **Hold** : Technologies à éviter ou à remplacer. Présentent des risques, sont obsolètes ou ne sont plus recommandées. À éviter pour de nouveaux projets.
**Important** : Tous les blips doivent utiliser ces rings standards (adopt, trial, assess, hold). Les anciens rings (core, strategic, support, legacy) ne sont plus utilisés.
## Historique des Technologies
Le Radar Technologique Laplank suit l'évolution des technologies au fil du temps avec un système d'historique par release.
@@ -61,7 +63,9 @@ Pour créer une nouvelle release :
3. Mettre à jour les blips existants si nécessaire (changement de ring, quadrant, description)
4. Ajouter les nouveaux blips pour les technologies nouvellement évaluées
4. **Migrer les rings si nécessaire** : S'assurer que tous les blips utilisent les rings standards (adopt, trial, assess, hold)
5. Ajouter les nouveaux blips pour les technologies nouvellement évaluées
## Métadonnées Business
@@ -70,7 +74,7 @@ Chaque technologie (blip) contient des métadonnées business :
### Métadonnées Standard
- **title** : Nom de la technologie
- **ring** : Anneau (adopt, trial, assess, hold)
- **ring** : Anneau (adopt, trial, assess, hold) - **IMPORTANT** : Utiliser uniquement ces rings standards
- **quadrant** : Quadrant business
- **tags** : Tags pour le filtrage
@@ -99,6 +103,8 @@ Le Radar Technologique Laplank inclut trois pages de stratégie accessibles depu
Ces pages sont générées dynamiquement via `public/strategie-script.js` qui convertit le contenu Markdown en HTML.
**Note** : Les fonctions d'ajout de liens dans le header ont été désactivées pour éviter les doublons. Tous les liens sont maintenant gérés par `Navigation.tsx`.
### Contenu des Pages
Le contenu des pages de stratégie est intégré directement dans `public/strategie-script.js` :
@@ -108,20 +114,31 @@ Le contenu des pages de stratégie est intégré directement dans `public/strate
Pour modifier le contenu, éditer directement `public/strategie-script.js` (sections `markdownContent`) ou les fichiers sources dans `docs/data/`.
## Navigation
Le header de navigation contient les liens suivants :
- **Comment utiliser le Radar Technologique ?** : Page d'aide
- **Vue d'ensemble des technologies** : Vue d'ensemble
- **👥 Équipe** : Page de visualisation équipe/technologies
**Important** : Tous les liens sont gérés par `Navigation.tsx`. Les scripts JavaScript qui ajoutaient des liens ont été désactivés pour éviter les doublons.
## Utilisation
### Ajouter une Nouvelle Technologie
1. Créer un fichier Markdown dans `radar-business/2025-01-15/`
2. Utiliser le format défini dans `radar-business/FORMAT-BLIP.md`
3. Remplir toutes les métadonnées
4. Ajouter la description et les sections recommandées
3. **Utiliser les rings standards** : adopt, trial, assess, hold
4. Remplir toutes les métadonnées
5. Ajouter la description et les sections recommandées
### Modifier une Technologie Existante
1. Ouvrir le fichier Markdown correspondant
2. Modifier les métadonnées ou le contenu
3. Mettre à jour la date si changement significatif
3. **Vérifier que le ring est standard** : adopt, trial, assess, hold
4. Mettre à jour la date si changement significatif
### Analyser le Radar
@@ -139,6 +156,18 @@ Pour régénérer les blips depuis `docs/data/technologies-duniter.md` :
node scripts/extract-technologies.js
```
## Migration des Rings
Si vous avez des blips avec les anciens rings, utilisez ce mapping :
- **core** → **adopt** : Technologies fondamentales en production
- **strategic** → **assess** : Technologies prometteuses à évaluer
- **support** → **adopt** : Technologies utilisées en production
- **trial** → **trial** : Déjà correct
- **legacy** → **hold** : Technologies obsolètes à remplacer
Le script `scripts/migrate-rings.sh` peut être utilisé pour automatiser cette migration.
## Interprétation des Résultats
### Technologies Critiques
@@ -181,7 +210,7 @@ Les technologies de commodité avec maintenanceCost élevé peuvent être optimi
### 2. Classification
- Classer par quadrant business
- Classer par ring (adopt, trial, assess, hold)
- Classer par ring (adopt, trial, assess, hold) - **utiliser uniquement ces rings**
- Évaluer les métadonnées
### 3. Analyse
@@ -200,7 +229,7 @@ Les technologies de commodité avec maintenanceCost élevé peuvent être optimi
### Template de Blip
Voir `radar-business/FORMAT-BLIP.md` pour le template complet.
Voir `radar-business/FORMAT-BLIP.md` pour le template complet avec toutes les métadonnées.
### Template d'Analyse
@@ -213,6 +242,7 @@ Le script `analyze-business-metrics.js` génère automatiquement un rapport d'an
- Mettre à jour les métadonnées trimestriellement
- Réviser les classifications annuellement
- Mettre à jour les coûts et risques
- **Vérifier que tous les blips utilisent les rings standards**
### Révision Stratégique
@@ -241,9 +271,8 @@ Voir [deploiement.md](./deploiement.md) pour les détails complets.
- **Stratégie business** : `docs/data/strategie-business.md`
- **Opportunités DataViz** : `docs/data/opportunites-dataviz.md` et `docs/data/opportunites-dataviz-details.md`
- **Technologies Duniter** : `docs/data/technologies-duniter.md`
- **Profil Team** : `docs/data/profil-team.md`
- **Profils Team** : `docs/data/team/*.md` (fichiers individuels)
## Support
Pour toute question ou contribution, consulter la documentation ou contacter l'équipe technique.

273
docs/app/troubleshooting.md Normal file
View 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

45
radar-business/FORMAT-BLIP.md
View File

@@ -7,7 +7,7 @@ Ce document définit le format standard pour les blips du radar business avec to
```markdown
---
title: "Nom de la technologie"
ring: core|strategic|support|legacy
ring: adopt|trial|assess|hold
quadrant: technologies-differentiantes|technologies-commodite|technologies-risque|technologies-emergentes
tags: [tag1, tag2]
businessImpact: high|medium|low
@@ -35,6 +35,7 @@ Description de l'impact sur le business.
## Compétences
- Nombre de personnes maîtrisant : N
- Membres de l'équipe : pseudo1, pseudo2
- Niveau moyen : expert|intermediate|beginner
- Risque de compétence manquante : low|medium|high
@@ -49,10 +50,10 @@ Recommandations stratégiques pour cette technologie.
- **title** (obligatoire) : Nom de la technologie
- **ring** (obligatoire) :
- `core` : Critique pour le business model
- `strategic` : Stratégique pour la croissance
- `support` : De support nécessaire
- `legacy` : À remplacer
- `adopt` : Technologies recommandées et utilisées avec succès en production. Stables, éprouvées, peuvent être adoptées en toute confiance pour de nouveaux projets.
- `trial` : Technologies à essayer. Prometteuses et testées avec succès dans certains contextes. À considérer pour de nouveaux projets.
- `assess` : Technologies à évaluer. Prometteuses mais nécessitent une évaluation approfondie avant adoption. À surveiller et tester.
- `hold` : Technologies à éviter ou à remplacer. Présentent des risques, sont obsolètes ou ne sont plus recommandées. À éviter pour de nouveaux projets.
- **quadrant** (obligatoire) :
- `technologies-differentiantes` : Créent un avantage concurrentiel
- `technologies-commodite` : Nécessaires mais non différenciantes
@@ -60,6 +61,8 @@ Recommandations stratégiques pour cette technologie.
- `technologies-emergentes` : Opportunités futures
- **tags** (optionnel) : Tags pour le filtrage
**Important** : Les anciens rings (core, strategic, support, legacy) ne sont plus utilisés. Tous les blips doivent utiliser les rings standards (adopt, trial, assess, hold).
### Métadonnées business
- **businessImpact** (obligatoire) :
@@ -97,22 +100,26 @@ Recommandations stratégiques pour cette technologie.
```markdown
---
title: "Rust / Substrate"
ring: core
title: "Rust"
ring: adopt
quadrant: technologies-differentiantes
tags: [blockchain, rust, substrate]
businessImpact: high
costToReplace: 200000
revenueImpact: direct
revenueImpact: indirect
riskLevel: medium
competencyLevel: intermediate
competencyLevel: beginner
maintenanceCost: 50000
differentiation: high
teamCoverage: 2
teamCoverage: 1
skillGap: high
---
Rust et le framework Substrate sont au cœur du développement de Duniter v2S, le nœud blockchain principal.
- **Utilisation** : Développement du nœud Duniter v2S (basé sur Substrate)
- **Projets** :
- `Duniter v2S` : Nœud blockchain principal
- `Ğcli-v2s` : Interface en ligne de commande Rust
- **Compétences requises** : Rust avancé, développement blockchain, Substrate framework
## Impact Business
@@ -125,8 +132,9 @@ Technologie critique pour le fonctionnement de la blockchain Ğ1. Sans cette tec
## Compétences
- Nombre de personnes maîtrisant : 2 (Eloïs, autres contributeurs)
- Niveau moyen : intermediate
- Nombre de personnes maîtrisant : 1
- Membres de l'équipe : elois
- Niveau moyen : beginner
- Risque de compétence manquante : high (peu de personnes, compétences critiques)
## Recommandations
@@ -137,3 +145,14 @@ Technologie critique pour le fonctionnement de la blockchain Ğ1. Sans cette tec
- Créer un plan de continuité en cas de départ de contributeurs clés
```
## Migration des rings
Si vous avez des blips avec les anciens rings, utilisez ce mapping :
- **core** → **adopt** : Technologies fondamentales en production
- **strategic** → **assess** : Technologies prometteuses à évaluer
- **support** → **adopt** : Technologies utilisées en production
- **trial** → **trial** : Déjà correct
- **legacy** → **hold** : Technologies obsolètes à remplacer
Le script `scripts/migrate-rings.sh` peut être utilisé pour automatiser cette migration.