# 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. ```mermaid 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 ``` ## Flux de génération ### 1. Processus général ```mermaid 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 ``` ### 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. ```javascript // 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. ```javascript // 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 ```javascript // 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. ```mermaid graph TD Backlog1[Backlog existant] --> Merger Backlog2[Nouveau backlog] --> Merger Merger --> BacklogFusion[Backlog fusionné] BacklogFusion --> Generator[Générateur Markdown] Generator --> Fichiers[Fichiers Markdown] ``` ### 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: ```javascript 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 ```mermaid 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 ``` ## 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 - [Format du backlog](./backlog-format.md) - [Architecture MCP](./mcp-server-architecture.md) - [GitHub Flavored Markdown](https://github.github.com/gfm/)