projet_gestion_commande/.claude/skills/plan-fonctionnalite/SKILL.md

name, description

name	description
plan-fonctionnalite	À invoquer avant d'implémenter toute nouvelle fonctionnalité ou modification significative de logique métier sur ce projet. Produit un plan détaillé (compréhension métier, sécurité, impact données, concurrence, tests) à valider avec l'utilisateur avant d'écrire du code — n'implémente rien tant que le plan n'est pas approuvé.

Plan de développement de fonctionnalité

Ce skill encadre le développement de toute fonctionnalité non triviale sur ce projet. Règle centrale : pas de code avant un plan validé par l'utilisateur, sauf si la demande est un pur bug fix local déjà bien compris (dans ce cas, ce skill ne s'applique pas — voir "Quand ne pas utiliser ce skill").

Étape 0 — Charger le contexte

Avant de rédiger le plan :

1. Invoquer/relire le skill comprehension-metier pour ancrer le raisonnement dans les vraies règles du domaine (rôles, cycle de vie commande, stock, parrainage, pénalités, paiements).
2. Repérer le(s) rôle(s) concerné(s) par la fonctionnalité (client / admin / livreur / cabine) et les fichiers existants correspondants (handlers/, db/) pour ne pas dupliquer un mécanisme déjà présent.
3. Si la demande est ambiguë sur une règle métier (ex: "qui peut faire X", "est-ce que ça affecte le stock"), poser la question plutôt que de supposer.

Étape 1 — Rédiger le plan

Utiliser EnterPlanMode si l'outil est disponible pour ce tour ; sinon présenter le plan en texte structuré et attendre confirmation explicite avant de coder. Le plan doit couvrir, dans cet ordre :

1. Résumé fonctionnel

Quoi, pour qui, pourquoi — en une ou deux phrases orientées métier (pas techniques).

2. Rôles et permissions

• Qui déclenche l'action, qui peut la voir, qui peut l'annuler/modifier.
• Nouveau endpoint ? → préciser le middleware d'auth (client vs admin/livreur/cabine) et la vérification de propriété de ressource.

3. Impact sur les données

• Nouvelles colonnes/tables ? Migration nécessaire (ALTER TABLE ... IF NOT EXISTS dans db_init.go, cohérent avec le style existant du projet).
• Tables existantes affectées, et sens des colonnes touchées (stock, solde, statut, compteur).

4. Flux détaillé

• Étapes séquencées, y compris les statuts intermédiaires si la fonctionnalité touche au cycle de vie d'une commande.
• Effets de bord obligatoires à tracer explicitement : stock (décrément/remboursement symétriques, y compris articles récompense), points de fidélité, solde de parrainage, pénalités, notifications Telegram.

5. Sécurité (voir skill securite-projet pour le détail)

• Validation d'entrée (bornes, whitelist de statuts, longueur).
• Requêtes paramétrées uniquement.
• Si paiement ou webhook externe impliqué : vérification de signature avant traitement.
• Pas de nouveau chemin d'auto-inscription ou de contournement d'autorisation.

6. Concurrence et atomicité

• Cette action peut-elle être rejouée (double-tap, retry réseau, webhook dupliqué) ? Si oui : mécanisme d'idempotence explicite (vérifier l'état courant avant d'agir, retourner un succès idempotent plutôt qu'une erreur ou un double effet).
• Lecture-puis-décision-puis-écriture sur une valeur partagée (stock, solde) ? → transaction unique avec FOR UPDATE, jamais une suite d'appels séparés.
• Toute création d'enregistrement (commande, paiement) doit être dans la même transaction que ses effets de bord critiques (décrément stock, débit solde) — pas de risque d'enregistrement "fantôme" si une étape suivante échoue.

7. Plan de test

• Cas nominal.
• Cas limite métier (stock insuffisant, solde insuffisant, commande déjà dans l'état cible, ressource appartenant à un autre utilisateur).
• Cas de concurrence si pertinent (double-tap simulé, deux requêtes quasi simultanées).
• Comment vérifier après implémentation (go build, go vet, test manuel via /verify ou l'app si UI concernée).

8. Points ouverts

Toute question métier ou technique non tranchée, à soumettre explicitement à l'utilisateur plutôt que de trancher seul par défaut.

Étape 2 — Validation puis implémentation

Ne commencer l'implémentation qu'après retour explicite de l'utilisateur sur le plan. Si l'utilisateur ne modifie rien, considérer le plan tel quel comme approuvé. Implémenter ensuite en suivant fidèlement les sections Sécurité et Concurrence du plan — elles ne sont pas optionnelles une fois validées.

Quand ne pas utiliser ce skill

• Bug fix ponctuel et bien circonscrit (ex: correction d'une requête, d'un typo, d'une regression déjà diagnostiquée) où un plan formel ajouterait de la friction sans valeur — corriger directement.
• Modification purement cosmétique (style, renommage local, commentaire).
• Le skill s'applique dès qu'une action touche : un nouveau statut ou transition de commande, un flux d'argent ou de points, une nouvelle route API, ou un changement de permission.