refactor: réorganiser la documentation en séparant app et data
- Création de docs/app/ pour la documentation de l'application - Création de docs/data/ pour les données utilisées par l'application - Déplacement de la documentation technique vers docs/app/ - Déplacement des données métier vers docs/data/ - Mise à jour de tous les liens et références dans les fichiers - Mise à jour des scripts (extract-technologies.js, analyze-business-metrics.js) - Mise à jour des fichiers JavaScript (custom.js, strategie-link.js) - Création de README.md dans docs/, docs/app/ et docs/data/ - Mise à jour du Readme.md principal avec les nouveaux chemins
This commit is contained in:
syoul
205
docs/app/developpement.md
Normal file
205
docs/app/developpement.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# Guide de développement
|
||||
|
||||
## Prérequis
|
||||
|
||||
- **Node.js** : Version 20 ou supérieure
|
||||
- **npm** : Gestionnaire de paquets Node.js
|
||||
- **Git** : Pour cloner et gérer le dépôt
|
||||
|
||||
## Installation
|
||||
|
||||
### Cloner le dépôt
|
||||
|
||||
```bash
|
||||
git clone https://git.open.us.org/AJR/TechradarDev.git
|
||||
cd TechradarDev
|
||||
```
|
||||
|
||||
### Installer les dépendances
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Cette commande installe le framework `aoe_technology_radar` depuis GitHub.
|
||||
|
||||
## Développement local
|
||||
|
||||
### Démarrer le serveur de développement (Radar Principal)
|
||||
|
||||
```bash
|
||||
npm run serve
|
||||
```
|
||||
|
||||
Le serveur démarre sur http://localhost:3000/techradar
|
||||
|
||||
### Démarrer le serveur de développement (Radar Business)
|
||||
|
||||
```bash
|
||||
npm run serve-business
|
||||
```
|
||||
|
||||
Le serveur démarre sur http://localhost:3006
|
||||
|
||||
**Note importante** : Le script `serve-business.sh` :
|
||||
- Sauvegarde temporairement `config.json` et le dossier `radar/`
|
||||
- Copie `radar-business/config-business.json` vers `config.json`
|
||||
- Copie `radar-business/2025-01-15/` vers `radar/`
|
||||
- Restaure la configuration originale à la sortie (Ctrl+C)
|
||||
|
||||
Le Radar Technologique Laplank est protégé par un mot de passe : `laplank-radar`
|
||||
|
||||
### Build de production
|
||||
|
||||
Pour générer les fichiers statiques :
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Les fichiers générés sont créés dans le répertoire `build/` (généré par le framework).
|
||||
|
||||
## Structure des fichiers radar
|
||||
|
||||
### Créer un nouveau blip
|
||||
|
||||
1. Créer un nouveau fichier Markdown dans le dossier de release approprié :
|
||||
```
|
||||
radar/2025-04-10/nom-technologie.md
|
||||
```
|
||||
|
||||
2. Utiliser le format suivant :
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Nom de la technologie"
|
||||
ring: adopt|trial|assess|hold
|
||||
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
|
||||
tags: [tag1, tag2]
|
||||
---
|
||||
|
||||
Description de la technologie en Markdown.
|
||||
|
||||
## Avantages
|
||||
|
||||
- Point 1
|
||||
- Point 2
|
||||
|
||||
## Cas d'usage
|
||||
|
||||
Description des cas d'usage chez AJR.
|
||||
```
|
||||
|
||||
### 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`
|
||||
- **tags** (optionnel) : Tableau de tags pour le filtrage
|
||||
|
||||
### Exemple complet
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Docker"
|
||||
ring: trial
|
||||
quadrant: tools
|
||||
tags: [devops, ci/cd]
|
||||
---
|
||||
|
||||
Docker est une plateforme de conteneurisation qui permet de packager des applications avec leurs dépendances.
|
||||
|
||||
## Avantages
|
||||
|
||||
- Isolation des environnements
|
||||
- Portabilité entre environnements
|
||||
- Facilite le déploiement
|
||||
|
||||
## Utilisation chez AJR
|
||||
|
||||
Nous utilisons Docker pour containeriser nos applications et faciliter le déploiement.
|
||||
```
|
||||
|
||||
## Modifier un blip existant
|
||||
|
||||
1. Localiser le fichier dans le dossier de release approprié
|
||||
2. Modifier le contenu Markdown
|
||||
3. Si nécessaire, modifier les métadonnées (ring, quadrant, tags)
|
||||
4. Tester localement avec `npm run serve`
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
## Ajouter des images
|
||||
|
||||
1. Placer les images dans `public/images/`
|
||||
2. Référencer dans les fichiers Markdown :
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
## Personnalisation CSS
|
||||
|
||||
Le fichier `custom.css` permet d'ajouter des styles personnalisés. Les styles sont appliqués globalement à l'application.
|
||||
|
||||
## 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 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
|
||||
3. **Images non chargées** : Vérifier le chemin relatif depuis `public/`
|
||||
|
||||
## 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
|
||||
|
||||
## Commandes utiles
|
||||
|
||||
```bash
|
||||
# Installer les dépendances
|
||||
npm install
|
||||
|
||||
# Démarrer le serveur de développement
|
||||
npm run serve
|
||||
|
||||
# Build de production
|
||||
npm run build
|
||||
|
||||
# Vérifier les fichiers modifiés
|
||||
git status
|
||||
|
||||
# Voir les différences
|
||||
git diff
|
||||
```
|
||||
|
||||
## Intégration continue
|
||||
|
||||
Le projet utilise Drone CI pour l'intégration continue. Voir `.drone.yml` pour la configuration.
|
||||
|
||||
Les builds automatiques :
|
||||
- Construisent l'image Docker
|
||||
- Déploient sur l'environnement de test
|
||||
- Envoient des notifications Telegram
|
||||
|
||||
Reference in New Issue
Block a user