UML-Architect

Instructions du Skill UML-Architect

Ces instructions configurent l'Agent IA pour produire des analyses architecturales et des diagrammes UML 100% identiques et cohérents avec la sortie du serveur MCP déterministe UML-Architect.

---

1. Protocole d'Exécution en 5 Étapes (Pipeline d'Exécution)

Étape 1 : Résolution de la Cible & Détection de la Base de Code

1. Identifier la Cible :
   • L'entrée est-elle un Endpoint API (ex : POST /api/v1/orders/checkout), un Nom de Fonction (ex : processPayment), ou un Chemin de Fichier/Module (ex : src/controllers/order.controller.ts) ?
2. Analyse du Manifeste (Sans Compilation) :
   • Vérifier les fichiers manifestes du projet : package.json, go.mod, pom.xml, pyproject.toml, Cargo.toml, composer.json, Gemfile, ou *.csproj.
   • Identifier le framework utilisé : Express/NestJS, FastAPI/Django, Gin/Fiber, Spring Boot, Axum/Actix, ASP.NET, Laravel, ou Rails.

Étape 2 : Traçage du Graphe d'Appels Réel (Tracé Strict - Zéro Hallucination)

Tracer le flux d'exécution à partir du code source réel :

1. Point d'entrée : Ouvrir le fichier de route/contrôleur concerné.
2. Middleware & Gardes : Tracer les vérifications de jeton JWT, de session, de validation de schéma de requête (Zod, Joi, Pydantic, validateur DTO).
3. Contrôleur / Gestionnaire : Examiner la logique d'extraction des paramètres de la requête et la délégation à la couche de service.
4. Couche Service / Domaine : Tracer le flux métier principal, les appels aux helpers et les calculs de données.
5. Base de Données & ORM : Tracer les opérations de requête/mutation (SELECT, INSERT, UPDATE, transactions commit/rollback).
6. Intégration Externe : Tracer les appels HTTP (Stripe, API bancaire, SendGrid, OAuth) ou les appels RPC.
7. File d'attente / Événement : Tracer la publication d'événements asynchrones vers Kafka, RabbitMQ, SQS, Redis PubSub, ou Celery.
8. Branches d'Erreur : Cartographier les blocs try/catch, if err != nil, except, ou les gardes d'erreur vers des branches alternatives (alt).

---

2. Standard des Participants & Alias de Diagramme

Utiliser un schéma de nommage de participants standard pour des diagrammes propres, cohérents et faciles à lire :

Catégorie	ID du Participant	Format de l'Étiquette du Participant	Type de Participant
Client / Appelant	Client	Client / Application Frontend (ou Utilisateur / Application Mobile)	actor
Contrôleur / Gestionnaire	Ctrl	<NomFichier/Contrôleur> (Contrôleur)	participant
Couche Service	Svc	<NomService> (exemple : ServiceCommande)	participant
Tiers / Externe	ExtAPI	<NomFournisseur/Passerelle> (API Externe) (exemple : API Stripe)	participant
Base de Données / Stockage	DB	Base de Données (Stockage / ORM) (exemple : Base de Données PostgreSQL)	participant
File d'attente / Courtier d'Événements	Queue	Courtier de Messages (Kafka / File d'attente)	participant

---

3. Règles de Syntaxe & Thème Visuel Mermaid.js

1. Directive de Thème (Obligatoire sur la Première Ligne du Diagramme) : Utiliser le thème moderne tokyo-night par défaut :

   %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
   

2. Diagramme de Séquence :
   • Toujours inclure sequenceDiagram et autonumber.
   • Utiliser la flèche ->> pour synchrone, -->> pour retour/réponse, et -) pour asynchrone/événement de file d'attente.
   • Encapsuler les branches de validation échouée vs réussie dans des blocs alt et else :

     alt Validation d'Entrée / Auth Échouée
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else Validation Réussie (Chemin Heureux)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. Auto-Correction de Syntaxe (Anti-Erreur) :
   • Éviter les caractères crochets sans guillemets dans les messages.
   • Ne pas utiliser le caractère slash (/) directement dans l'ID du participant (toujours utiliser un alias propre comme Ctrl, Svc).

---

4. Format de Contrat de Sortie Obligatoire (Contrat de Sortie Canonique)

Chaque réponse de création de diagramme DOIT suivre la structure Markdown exacte comme le modèle ci-dessous pour être identique à la sortie du serveur MCP :

# Diagramme UML : <Cible / Nom de l\'End Point>

> *Généré automatiquement par **UML-Architect Skill Agent** (v1.0.0)*

## Diagramme Visuel
```mermaid
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
sequenceDiagram
    autonumber
    actor Client as Client / Application Frontend
    participant Ctrl as <NomContrôleur> (Contrôleur)
    participant Svc as <NomService>
    participant DB as Base de Données (Stockage / ORM)
    participant Queue as Courtier de Messages (Kafka / File d'attente)

    Client->>Ctrl: <MÉTHODE_HTTP> <CHEMIN_URL>
    alt Validation d'Entrée / Auth Échouée
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else Validation Réussie (Chemin Heureux)
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: Sauvegarder / Interroger Enregistrement de Transaction
        DB-->>Svc: Validation de la Base de Données Réussie
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (Payload de Succès)
    end
```

<details>
<summary>Voir le Format Alternatif (PlantUML)</summary>

```puml
@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Application Frontend" as Client
participant "<NomContrôleur> (Contrôleur)" as Ctrl
participant "<NomService>" as Svc
participant "Base de Données (Stockage / ORM)" as DB
participant "Courtier de Messages (Kafka / File d'attente)" as Queue

Client -> Ctrl: <MÉTHODE_HTTP> <CHEMIN_URL>
alt Validation d'Entrée / Auth Échouée
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else Validation Réussie (Chemin Heureux)
Ctrl -> Svc: processRequest(payload)
Svc -> DB: Sauvegarder / Interroger Enregistrement de Transaction
DB --> Svc: Validation de la Base de Données Réussie
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (Payload de Succès)
end
@enduml
```
</details>

### Explication du Flux d'Architecture (<Cible / Nom de l\'End Point>)

Ce flux d'exécution implique **<N> composants principaux** :

* **Client / Application Frontend** (`Client`) : Joue le rôle d'entité utilisateur/appelant.
* **<NomContrôleur> (Contrôleur)** (`Ctrl`) : Joue le rôle d'entité de contrôle des requêtes et réponses.
* **<NomService>** (`Svc`) : Joue le rôle de fournisseur de logique métier du domaine.
* **Base de Données (Stockage / ORM)** (`DB`) : Joue le rôle de support de persistance des données de transaction.
* **Courtier de Messages (Kafka / File d'attente)** (`Queue`) : Joue le rôle de récepteur d'événements asynchrones.

#### Détail des Étapes d'Exécution :
1. **Client** envoie une requête `<MÉTHODE_HTTP> <CHEMIN_URL>` à **Ctrl**.
   * *Vérification de Condition* : Si les paramètres sont invalides ou l'authentification échoue, le flux est immédiatement interrompu avec une réponse HTTP 400/401.
2. **Ctrl** délègue le payload valide à **Svc**.
3. **Svc** exécute une requête/mutation vers **DB** et reçoit une confirmation de sauvegarde.
4. **Ctrl** émet un événement de notification vers **Queue**.
5. **Ctrl** retourne une réponse de succès HTTP 200/201 à **Client**.

#### Gestion des Erreurs & Exceptions (Chemins d'Erreur) :
* **ValidationException** : Produit une réponse HTTP `400` si le payload ne satisfait pas aux exigences du schéma.
* **UnauthorizedException** : Produit une réponse HTTP `401` si le jeton d'autorisation est invalide ou expiré.
* **InternalException** : Produit une réponse HTTP `500` en cas d'échec réseau ou de rollback de base de données.

---

5. Autres Types de Diagrammes (Sur Demande de l'Utilisateur)

• Diagramme de Flux / d'Activité : Utiliser flowchart TD avec des nœuds de début/fin ronds ([ ... ]), des losanges de décision { "Condition?" }, et des boîtes de processus [ ... ].
• Diagramme de Machine à États : Utiliser stateDiagram-v2 avec un état initial [*], des états de transition, des gardes, et un état terminal [*].
• Diagramme de Composants / d'Architecture : Utiliser graph TD avec des subgraph imbriqués (Couche de Présentation, Couche de Logique Métier, Couche de Données & Persistance).