Spécifications de visualisation du flux de code
Cette compétence fournit un ensemble de modèles et de méthodes réutilisables pour analyser le flux de code et générer une documentation visuelle.
Principe fondamental : Expliquer clairement avec du texte et des diagrammes ASCII "d'où viennent les données, par quelles couches elles passent et où elles aboutissent".
Quand l'utiliser
Utilisez cette compétence dans les contextes suivants :
- L'utilisateur demande "comment fonctionne une fonctionnalité"
- Une nouvelle fonctionnalité nécessite une conception du flux de données
- Avant une refactorisation, vous devez comprendre la logique existante
- Rédaction de documentation technique ou d'explications architecturales
- Pendant une revue de code, besoin de visualiser la chaîne d'appels
Modèles principaux
1. Diagramme de flux complet (comparaison multi-scénarios)
Convient pour : analyser les différents scénarios d'utilisation d'une fonctionnalité (par exemple manuel vs automatique, succès vs échec)
┌─────────────────────────────────────────────────────────────────────┐
│ Nom de la fonctionnalité (ex : Cycle de vie │
│ complet de la gestion des limites) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Scénario 1 : Nom du scénario (ex : Interrogation automatique de l'état
des limites)
═══════════════════════════════════════════════════════════════════════
Commande utilisateur
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ Couche CLI │ Appelle la fonction Flow
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Couche Flow │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Couche Data │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Système externe / Base de │
│ données │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Renvoie les données
▼
┌──────────────────────────────────┐
│ Traitement des données │
│ (Parsing / Transformation) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Classe de données │ ← Explique pourquoi on la │
│ de retour │ conserve / simplifie │
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Formatage de sortie │
│ par la couche CLI │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Exemple de sortie terminal ║
║ (Entouré de bordures pour mettre en évidence ║
║ le résultat vu par l'utilisateur final) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Scénario 2 : Un autre scénario
═══════════════════════════════════════════════════════════════════════
(Répéter la structure ci-dessus, en mettant en évidence les différences)
2. Explication de la structure de la table de base de données
Convient pour : expliquer les tables de base de données impliquées dans une fonctionnalité
CREATE TABLE nom_table (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Explique le rôle de la clé primaire
champ1 TEXT NOT NULL, -- Explique la signification du champ
champ2 TEXT, -- Signification métier de NULL
...
);
-- Index (explique pourquoi cet index est nécessaire)
CREATE INDEX idx_xxx ON nom_table(champ1, champ2);
Exemple de données :
| id | champ1 | champ2 | champ3 | Description |
|---|---|---|---|---|
| 42 | valeur1 | valeur2 | valeur3 | Explique la signification métier de cet enregistrement |
| 43 | ... | ... | ... | ... |
Requête typique :
-- Explication du scénario : quand faut-il interroger de cette façon ?
SELECT * FROM nom_table
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Diagramme de chaîne d'appels en couches (version simplifiée)
Convient pour : expliquer rapidement les relations d'appel entre fonctions
Couche CLI (_do_xxx)
│
└─> Couche Flow (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/Client (xxx_client.fetch)
│
└─> API externe (HTTP GET ...)
4. Tableau d'analyse de conception des classes de données
Convient pour : évaluer si les classes de données intermédiaires sont nécessaires
| Nom de la classe | Nombre de champs | Utilisation | Verdict | Raison |
|---|---|---|---|---|
XxxResult | 6 | Agrégation multi-champs + affichage CLI | ✅ Conserver | Satisfait au "principe de nécessité minimale" |
XxxWrapper | 1 | Emballage d'un seul champ | ❌ Supprimer | Emballage excessif, retourner directement le type original |
XxxItem | 3 | Élément de détail d'une liste | ✅ Conserver | A une signification métier |
Exemple de comparaison :
# ❌ Emballage excessif
@dataclass
class XxxResult:
champ: SomeType # Un seul champ
def xxx_flow() -> XxxResult:
return XxxResult(champ=valeur)
# ✅ Simplifié
def xxx_flow() -> SomeType: # Retour direct
return valeur
5. Annotation des points métier clés
Convient pour : mettre en évidence les règles métier et les décisions de conception
┌─────────────────────────────────────────────────────────────┐
│ Points métier clés │
├──────────────────────┬──────────────────────────────────────┤
│ Pourquoi cette │ Décision spécifique │
│ conception ? │ │
├──────────────────────┼──────────────────────────────────────┤
│ • Précision des │ Montants en Decimal, 2 décimales │
│ données │ │
│ • Idempotence │ Contrainte d'unicité sur │
│ │ (fund_code, date) │
│ • Traçabilité │ record_id comme identifiant unique │
│ │ global │
└──────────────────────┴──────────────────────────────────────┘
Comment utiliser
Étape 1 : Définir l'objectif de l'analyse
Répondez aux questions suivantes :
- De quelle fonctionnalité l'utilisateur souhaite-t-il comprendre le flux ?
- Combien de scénarios cette fonctionnalité a-t-elle ? (Succès/échec, manuel/automatique, etc.)
- Quelles couches sont impliquées ? (CLI → Flow → Data → DB/API)
- Quelles sont les classes de données clés ? Pourquoi sont-elles conçues ainsi ?
Étape 2 : Choisir le modèle approprié
- Comparaison multi-scénarios → Modèle 1 (Diagramme de flux complet)
- Flux unique → Modèle 3 (Diagramme d'appel en couches)
- Conception de base de données → Modèle 2 (Structure de table + données exemple)
- Évaluation des classes de données → Modèle 4 (Tableau d'analyse)
Étape 3 : Remplir le contenu
Principes :
- Utiliser des diagrammes ASCII plutôt que de longs textes
- Utiliser des flèches (
│ ▼ ┐ ┘ └ ├ ─) pour relier les flux de données - Utiliser des bordures (
┌ ┐ └ ┘ │ ─) pour séparer les couches - Utiliser des bordures doubles (
╔ ╗ ╚ ╝ ║ ═) pour mettre en évidence les parties visibles par l'utilisateur - Ajouter des commentaires aux nœuds clés (
← Explication)
Conventions d'utilisation des symboles :
| Symbole | Utilisation | Exemple |
|---|---|---|
│ ▼ | Flux vertical | Données de haut en bas |
→ ← | Explication horizontale | record_id: int ← Clé primaire de la base |
┌ ┐ └ ┘ | Bordure simple | Encadrer les blocs de code, les commandes |
╔ ╗ ╚ ╝ | Bordure double | Mettre en évidence la sortie terminal, les résultats importants |
═══ | Ligne de séparation | Séparer différents scénarios |
Étape 4 : Ajouter une analyse comparative
Avant vs Après (scénario de refactorisation) :
# Avant (version problématique)
...code...
# Problèmes :
# - Emballage excessif
# - Champs redondants
# - Augmente la charge cognitive
# Après (version améliorée)
...code...
# Améliorations :
# - Retour direct d'un type significatif
# - Réduction des couches intermédiaires
# - Coût de maintenance réduit
Exemples concrets
Exemple 1 : Flux de gestion des limites (version complète)
(Voir l'exemple du modèle 1 ci-dessus, développant le flux complet des 4 scénarios)
Exemple 2 : Évaluation des classes de données (module fund_restriction)
| Fonction | Retour précédent | Retour actuel | Verdict | Raison |
|---|---|---|---|---|
add_restriction | AddRestrictionResult (6 champs) | Conserver | ✅ | Le CLI a besoin d'afficher tous les champs |
end_restriction | EndRestrictionResult (4 champs) | bool | ❌ | Seulement besoin de succès/échec |
check_trading_status | CheckStatusResult (2 champs) | ParsedRestriction | None | ❌ | Simple emballage |
Liste de vérification (Checklist)
Lors de la génération d'un document de visualisation de flux, assurez-vous d'inclure :
- Aperçu de haut niveau (objectif de la fonctionnalité, modules impliqués)
- Énumération des scénarios (succès/échec, manuel/automatique, etc.)
- Diagramme de flux en couches (CLI → Flow → Data → Externe)
- Structure de la table de base de données (si impliquée)
- Données d'exemple et requêtes (pour faciliter la compréhension)
- Explication des classes de données clés (pourquoi conservées/simplifiées)
- Raison de la conception (pourquoi cette approche ?)
- Points d'extension futurs (TODO ou interfaces réservées)
Anti-modèles (à ne pas faire)
❌ Description purement textuelle du flux
D'abord, la couche CLI appelle la fonction _do_xxx, puis _do_xxx appelle la fonction xxx_flow de la couche Flow,
ensuite xxx_flow appelle la méthode xxx_repo.get de la couche Data...
✅ Utilisation d'un diagramme ASCII
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ Tableau sans point clé
| Champ | Type |
|---|---|
| id | int |
| name | str |
✅ Mise en évidence de la signification métier
| Champ | Type | Description | Contrainte métier |
|---|---|---|---|
| id | int | Clé primaire | Généré automatiquement, unique globalement |
| name | str | Nom du fonds | Non nul, utilisé pour l'affichage |
❌ SQL sans explication de scénario
SELECT * FROM table WHERE id = ?;
✅ Avec scénario métier
-- Scénario : L'utilisateur consulte le détail d'un enregistrement de restriction
SELECT * FROM fund_restrictions WHERE id = ?;
-- Scénario : Lors de l'analyse DCA, vérifier si un jour donné est limité
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Collaboration avec d'autres compétences
- code-style : Suivre les conventions de codage lors de l'écriture d'exemples de code
- architecture : Les diagrammes de flux doivent respecter les contraintes d'architecture en couches
- dev-workflow : Lire le code et la documentation pertinents avant d'analyser le flux
Résumé
La valeur fondamentale de cette compétence :
- Modèles réutilisables : Réduit le temps de démarrage à partir de zéro
- Style visuel unifié : Diagrammes ASCII + tableaux + bordures
- Perspective métier : Pas seulement le flux de code, mais aussi le "pourquoi"
- Analyse comparative : Avant/après refactorisation, comparaison multi-scénarios
- Vérification par liste : Assure qu'aucune information clé n'est omise
Fréquence d'utilisation : Chaque fois qu'il est nécessaire d'expliquer "comment fonctionne une fonctionnalité".