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

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.