Aide & Documentation · Prévision des ventes

📖 Glossaire — Méthodes & outils

Ce fichier Excel n'a pas d'onglet glossaire intégré — les termes de méthode sont donc expliqués ici.

TREND (Excel)	Fonction Excel qui calcule une régression linéaire (droite qui approche au mieux une série de points) — utilisée pour corriger les mois atypiques (outliers).
Outlier	Mois dont la valeur s'écarte anormalement de la tendance (ex. promo exceptionnelle, rupture de stock). Détecté si l'écart dépasse le seuil `$B$5` (15% par défaut).
Indice saisonnier	Rapport entre les ventes d'un mois et la moyenne annuelle — au-dessus de 1 = saison haute, en dessous = saison basse.
MAPE	Mean Absolute Percentage Error — écart moyen en % entre la prévision et la réalité. Plus c'est bas, meilleure est la méthode (voir tableau des résultats de référence dans `CONTEXTE.md`).
Back-test	Test d'une méthode de prévision sur des données déjà connues (ex. prédire Y-1 à partir de Y-3/Y-2) pour vérifier sa fiabilité avant de l'appliquer au futur.
H1 / H2 / H3	Les 3 hypothèses de tendance utilisées par les onglets Python/Combinée, selon que la tendance longue (T36) et récente (T12/T3) sont d'accord ou non — détail dans `CONTEXTE.md`.
Python	Requis pour régénérer le fichier Excel (`build_clean.py`) et lancer les tests — pas nécessaire pour simplement consulter le fichier.
Claude / Claude Code	Claude = l'IA sur claude.ai. Claude Code = la version qui travaille directement sur vos fichiers depuis un terminal.

🚀 Installer et lancer

Consulter le fichier ne demande rien de particulier ; le modifier demande Python

① Consulter le fichier Excel (aucune installation)

☐ Double-cliquez sur Lancer-Application.bat (ou ouvrez directement plan-ventes-forecast-final.xlsx) avec Excel ou LibreOffice Calc (gratuit).

☐ Ou ouvrez plan-ventes-forecast-export.html dans un navigateur — snapshot en lecture seule, aucun logiciel requis.

② Pouvoir le modifier avec Claude Code

Nécessite Node.js (pour Claude Code) et Python (pour régénérer le fichier).

Installer Node.js

https://nodejs.org — version LTS, installation par défaut.

Installer Claude Code

npm install -g @anthropic/claude-code

Installer Python

https://www.python.org/downloads/ — cocher "Add to PATH" à l'installation.

Ouvrir PowerShell dans le dossier du projet, puis lancer Claude Code

claude

Décrivez ensuite votre modification (voir "Exemples de prompts").

Erreurs fréquentes

Message	Solution
'node' n'est pas reconnu	Node.js pas installé, ou terminal pas rouvert après l'installation.
'python' n'est pas reconnu	Python pas installé, ou pas ajouté au PATH lors de l'installation.
ModuleNotFoundError: openpyxl / win32com	`pip install openpyxl pywin32` — Excel doit être installé pour `win32com`.

🗺️ Comment c'est construit

Le minimum à savoir avant de demander une modification

💡 Une seule source de vérité : le script Python

build_clean.py contient les données par défaut (historique de ventes, promos, paramètres) et régénère entièrement le fichier .xlsx à chaque exécution — sauf l'onglet 'Données', conçu pour être édité directement dans Excel (Python/Combinée/Simplifiée le reprennent par formule), à condition de ne pas relancer le script après (il écraserait vos changements avec le CSV ou les valeurs par défaut). Pour charger une autre liste de ventes de façon durable, éditez plutôt ventes_historique_IN.csv puis relancez. Ne jamais modifier les autres onglets directement.

📁 Les fichiers du dossier

build_clean.py	Script source unique — génère tout le fichier Excel.
ventes_historique_IN.csv	CSV d'entrée optionnel (produit,annee,mois,ventes,promo,bonus) — s'il existe, remplace les données historiques par défaut.
plan-ventes-forecast-final.xlsx	Fichier Excel généré — ne jamais éditer à la main (sauf l'onglet 'Données', voir ci-dessus).
recalc.py	Force un recalcul Excel et vérifie l'absence d'erreur de formule.
export_html.py	Génère `plan-ventes-forecast-export.html`, un snapshot HTML en lecture seule.
test_regression.py	Suite de tests de non-régression.
CONTEXTE.md	Détail des 8 onglets, des colonnes, des paramètres et des décisions de conception.

📊 Les 8 onglets

Historique → Méthode 0 → Initiale → Optimisée → Python → Combinée → Simplifiée → Conclusion — chaque onglet est une méthode de prévision plus élaborée que la précédente, avec son MAPE (taux d'erreur) comparé dans l'onglet Conclusion. Le détail complet (formules, colonnes, paramètres) est dans CONTEXTE.md, pas dupliqué ici.

🤖 Comment l'IA est utilisée

Comme pour tous les projets de TWIN agents IA : le fichier Excel généré n'appelle jamais Claude. C'est vous qui utilisez Claude Code, en dehors du fichier, pour faire évoluer build_clean.py.

✏️ Demander une modification à Claude Code

Vous n'avez pas besoin de savoir coder — juste de décrire précisément ce que vous voulez

1️⃣ Précisez l'onglet ou le paramètre concerné (ex. seuil outlier $B$5, poids $B$8-10) — évite que Claude Code cherche au mauvais endroit.

2️⃣ Décrivez le comportement actuel puis voulu : "Actuellement X vaut Y, je voudrais Z."

3️⃣ Une demande à la fois — plus facile à vérifier et à annuler si besoin.

4️⃣ Si la donnée vient des tableaux de build_clean.py (A_Y3, B_Y2...), donnez les nouvelles valeurs précisément.

5️⃣ Demandez toujours python3 build_clean.py puis python3 recalc.py après coup (voir "Tests de non-régression").

💡 Exemples de prompts

À copier-coller dans Claude Code, pas dans claude.ai

🎚️ Changer un paramètre

Dans build_clean.py, le seuil de détection outlier ($B$5) est actuellement 0,15 (15%). Je voudrais le passer à 0,20 (20%). Régénère le fichier Excel et vérifie avec recalc.py qu'il n'y a aucune erreur de formule.

📈 Mettre à jour l'historique de ventes

Dans build_clean.py, remplace le tableau A_Y1 (Produit A, année la plus récente) par ces 12 valeurs : [liste les 12 valeurs ici]. Régénère le fichier et lance test_regression.py pour confirmer que rien d'autre n'a changé.

🐛 Corriger un problème connu

Corrige le problème n°2 listé dans CONTEXTE.md (MAPE circulaire pour le Produit B, onglets Python et Combinée) : utilise la formule back-test proxy proposée (=SUMPRODUCT(ABS(F*(F/E)-G)/G)/12). Vérifie que le nouveau MAPE est cohérent avec un vrai back-test.

✅ Tests de non-régression

Deux niveaux complémentaires : vérification automatisée, et vérification visuelle par vous

⚠️ Ne considérez jamais une modification terminée juste parce que Claude Code dit "c'est fait" — vérifiez vous-même.

🤖 Niveau 1 — Suite automatisée (recalcul Excel réel)

Demandez à Claude Code de lancer, ou lancez vous-même :

python3 test_regression.py

Vérifie 48 points : recalcul Excel réel (via Excel COM, pas une simulation) et absence d'erreur de formule, hygiène du fichier (pas de macro VBA, pas de lien externe, pas d'élément caché), exactitude des valeurs calculées sur les 8 onglets, test fonctionnel de planification glissante, validité syntaxique des scripts, absence de secret codé en dur.

🖱️ Niveau 2 — Vérification visuelle dans Excel/LibreOffice

☐ Ouvrir plan-ventes-forecast-final.xlsx après régénération — vérifier qu'aucune cellule n'affiche #REF!, #VALUE! ou #DIV/0!

☐ Vérifier l'onglet modifié + l'onglet Conclusion (il agrège tous les autres — une erreur ailleurs s'y répercute)

☐ Si un paramètre partagé a changé ($B$5-14), vérifier les onglets Python, Combinée et Simplifiée (ils l'utilisent tous)

🏁 Validation de la version finale

Une fois toutes vos modifications terminées

☐ python3 build_clean.py exécuté sans erreur

☐ python3 test_regression.py → 52/52 tests passés

☐ python3 recalc.py plan-ventes-forecast-final.xlsx 90 → 0 erreur de formule

☐ Si l'export HTML doit refléter les changements : relancer python3 export_html.py

☐ Ouverture manuelle du fichier (pas juste via Claude Code) pour confirmer un usage réel normal

🛠️ Dépannage

Situation	Solution
Le fichier Excel affiche des erreurs de formule	Relancer `python3 build_clean.py` puis `recalc.py` — ne jamais corriger une cellule à la main.
test_regression.py échoue sur "recalcul Excel"	Excel doit être installé et fermé (pas d'instance ouverte) avant de lancer le test.
Le MAPE semble irréaliste après une modification	Vérifiez que ce n'est pas le problème connu n°2 (comparaison circulaire) — voir `CONTEXTE.md`.
Je veux une copie de secours avant un gros changement	Copiez `build_clean.py` et le `.xlsx` (clic droit → Copier/Coller) avant de demander la modification.

🔒 Sécurité

Vérifications automatisées le 2026-07-19 — pas d'audit manuel ponctuel comme sur le projet "Pilotage commercial"

🎯 Pourquoi la surface de risque est limitée ici

Script Python local sans serveur, sans interface web, sans donnée personnelle (produits génériques A/B, chiffres agrégés synthétiques — voir la revue RGPD du 2026-07-21 dans le README racine). Le fichier Excel généré ne contient que des formules et valeurs, pas de macro ni de script embarqué.

✅ Vérifié par test_regression.py (52 tests, à chaque modification)

OK Aucun secret codé en dur (clé API, mot de passe, clé privée)

OK Aucune macro VBA dans le fichier Excel généré

OK Aucun lien externe ni élément caché dans le classeur

OK Syntaxe Python valide (py_compile) sur tous les scripts du projet

Si une future évolution ajoute des données clients réelles (au lieu des produits génériques actuels), appliquez le même principe que le projet "Pilotage commercial" : ne stocker/traiter ces données que localement, et documenter les précautions RGPD correspondantes.

🔐 Charte d'utilisation de l'IA

L'usage des outils d'IA sur ce projet est encadré par une charte commune aux 6 projets de TWIN agents IA — usages/outils autorisés, données interdites, validation humaine avant action, contact référent : Charte_IA.md.