Skip to content

markdown-generation.md

Latest commit

 

History

History
256 lines (200 loc) · 7.69 KB

markdown-generation.md

File metadata and controls

256 lines (200 loc) · 7.69 KB

Système de génération Markdown

Date de dernière modification: 12/05/2025
Version: 1.7.1

Introduction

Le système de génération markdown d'Agile Planner transforme les structures de backlog en fichiers markdown organisés selon une hiérarchie claire. Ce document détaille l'architecture, les composants et le fonctionnement du système.

Architecture modulaire

Le générateur markdown a été conçu selon une architecture modulaire pour maximiser la maintenabilité et permettre les évolutions futures.

graph TB
    subgraph "API externe"
        MDG[markdown-generator.js] --> MI[markdown/index.js]
    end
    
    subgraph "Formatters"
        MI --> EF[epic-formatter.js]
        MI --> FF[feature-formatter.js]
        MI --> SF[story-formatter.js]
    end
    
    subgraph "Utilitaires"
        Utils[utils.js] --> SlugGen[Générateur de slug]
        Utils --> ErrHandle[Gestionnaire d'erreurs]
        Utils --> TemplateEngine[Moteur de templates]
    end
    
    EF --> Utils
    FF --> Utils
    SF --> Utils
Loading

Flux de génération

1. Processus général

sequenceDiagram
    participant Client
    participant MDGen as Markdown Generator
    participant Formatters as Formatters (Epic, Feature, Story)
    participant FS as File System
    
    Client->>MDGen: generateMarkdownFilesFromResult(backlog, outputDir)
    MDGen->>MDGen: Valider la structure du backlog
    MDGen->>FS: Créer la structure de dossiers
    
    loop Pour chaque epic
        MDGen->>Formatters: Formater l'epic
        Formatters->>FS: Écrire epic.md
        
        loop Pour chaque feature de l'epic
            MDGen->>Formatters: Formater la feature
            Formatters->>FS: Écrire feature.md
            
            loop Pour chaque story de la feature
                MDGen->>Formatters: Formater la story
                Formatters->>FS: Écrire [story-slug].md
            end
        end
    end
    
    loop Pour chaque story orpheline
        MDGen->>Formatters: Formater la story orpheline
        Formatters->>FS: Écrire [story-slug].md dans /orphan-stories
    end
    
    MDGen-->>Client: Résultat de la génération
Loading

2. Étapes détaillées

  1. Validation du backlog - Vérifie que le backlog est bien formé
  2. Création de la structure - Crée les dossiers nécessaires
  3. Génération des epics - Génère les fichiers markdown pour chaque epic
  4. Génération des features - Génère les fichiers markdown pour chaque feature
  5. Génération des stories - Génère les fichiers markdown pour chaque story
  6. Traitement des orphelins - Gère les stories qui ne sont pas associées à une feature

Composants du système

1. Module façade (markdown-generator.js)

Ce module assure la compatibilité avec les versions précédentes et sert de point d'entrée unique pour le système de génération markdown.

// Exemple simplifié d'utilisation
const { generateMarkdownFiles } = require('./lib/markdown-generator');

await generateMarkdownFiles(backlogData, outputDir);

2. Générateur principal (markdown/index.js)

C'est le cœur du système qui orchestre tout le processus de génération.

// Utilisation du générateur principal
const { createMarkdownGenerator } = require('./lib/markdown/index');
const generator = createMarkdownGenerator();
await generator.generateMarkdownFilesFromResult(backlog, outputDir);

3. Formateurs spécialisés

Chaque type d'élément (epic, feature, story) possède son propre formateur qui définit comment transformer les données en markdown.

Formateur Fichier Responsabilité
Epic Formatter epic-formatter.js Génère les fichiers epic.md
Feature Formatter feature-formatter.js Génère les fichiers feature.md
Story Formatter story-formatter.js Génère les fichiers [story-slug].md

4. Utilitaires communs

// Exemple de génération de slug
const { createSlug } = require('./utils');
const slug = createSlug('Mon titre avec des espaces'); // -> 'mon-titre-avec-des-espaces'

Structure de fichiers générée

.agile-planner-backlog/
├── backlog.json
├── epics/
│   └── [epic-slug]/
│       ├── epic.md
│       └── features/
│           └── [feature-slug]/
│               ├── feature.md
│               └── user-stories/
│                   └── [story-slug].md
└── orphan-stories/
    └── [story-slug].md

Mécanismes de fusion

Le système permet la fusion de backlogs existants avec de nouveaux backlogs, ce qui est particulièrement utile lors des itérations successives.

graph TD
    Backlog1[Backlog existant] --> Merger
    Backlog2[Nouveau backlog] --> Merger
    Merger --> BacklogFusion[Backlog fusionné]
    BacklogFusion --> Generator[Générateur Markdown]
    Generator --> Fichiers[Fichiers Markdown]
Loading

Stratégies de fusion

Élément Stratégie de fusion
Project Info Fusion des métadonnées du projet
Epics Fusion par ID ou par titre si ID absent
Features Fusion par ID ou par titre si ID absent
Stories Fusion par ID ou par titre si ID absent
Iterations Ajout de nouvelles itérations, mise à jour des existantes
MVP Mise à jour des informations de MVP

Personnalisation des templates

Les templates de génération peuvent être personnalisés en modifiant les constantes définies dans les formateurs respectifs:

const epicFileInstructions = `Ce document est généré par Agile Planner et contient des informations sur un Epic.
Les User Stories associées se trouvent dans les sous-dossiers.
Vous pouvez explorer le backlog complet en naviguant dans les liens.`;

Modèle de données

classDiagram
    class Backlog {
        +String projectName
        +String projectDescription
        +Epic[] epics
        +Story[] orphan_stories
        +Iteration[] iterations
        +MVP mvp
    }
    
    class Epic {
        +String id
        +String title
        +String description
        +String slug
        +Feature[] features
    }
    
    class Feature {
        +String id
        +String title
        +String description
        +String slug
        +Story[] stories
    }
    
    class Story {
        +String id
        +String title
        +String description
        +String slug
        +String[] acceptance_criteria
        +String[] technical_tasks
        +String priority
        +String estimate
    }
    
    class Iteration {
        +String id
        +String title
        +String description
        +StoryRef[] stories
    }
    
    class MVP {
        +String description
        +StoryRef[] stories
    }
    
    class StoryRef {
        +String id
        +String title
        +String description
    }
    
    Backlog "1" --> "*" Epic
    Backlog "1" --> "*" Story : orphan_stories
    Backlog "1" --> "0..1" MVP
    Backlog "1" --> "*" Iteration
    Epic "1" --> "*" Feature
    Feature "1" --> "*" Story
    Iteration "1" --> "*" StoryRef
    MVP "1" --> "*" StoryRef
Loading

Bonnes pratiques

  1. Unicité des identifiants - Toujours s'assurer que les éléments ont des IDs uniques
  2. Validation des slugs - Vérifier que les slugs sont valides pour éviter les problèmes de chemins
  3. Gestion des erreurs - Capturer et logger les erreurs pour faciliter le débogage
  4. Éviter les boucles infinies - Limiter la profondeur de récursion dans les structures imbriquées

Références