---
name: s05-top-suppliers-comparison
scenario: S05
description: Top fournisseurs par dépense avec comparaison période précédente — les IDs sont retournés sans noms, nécessite un resolve séparé
tags: [spend-analysis, suppliers, comparison, year-over-year, ids]
when_to_use: Quand on veut identifier les plus gros fournisseurs et leur évolution vs la période précédente
risk: P2 — spendesk_analyze_spend groupBy=supplier retourne uniquement les IDs fournisseurs, sans nom. Pour afficher les noms, il faut appeler get_suppliers ou get_supplier_by_id pour chaque ID.
---

# Instructions — Top fournisseurs avec comparaison YoY

## ⚠️ Fournisseurs retournés sans nom

`spendesk_analyze_spend` groupBy=supplier retourne la clé `key` = **ID fournisseur uniquement**.
Le champ `name` n'est pas présent dans la réponse.

Pour afficher les noms :
1. Collecter tous les IDs du top-N fournisseurs
2. Appeler `get_suppliers(ids=[id1, id2, ...])` en une seule fois
3. Joindre les noms par ID

## ⚠️ amountChange sur la row "Others"

La row "Others" inclut aussi `previousAmount` et `amountChange`. Si "Others" croît fortement, le portefeuille fournisseurs s'élargit plus vite que le top.

## Étape 1 — Analyse top fournisseurs avec comparaison

```json
{
  "companyId": "...",
  "fromDate": "YYYY-MM-DD",
  "toDate": "YYYY-MM-DD",
  "groupBy": ["supplier"],
  "compareWithPreviousPeriod": true,
  "limit": 15
}
```

→ La période précédente est automatiquement calculée (même durée, juste avant `fromDate`).
→ `limit: 15` pour voir plus que le top-10 par défaut.

## Étape 2 — Interpréter compareWithPreviousPeriod

Chaque ligne retourne :
- `amount` : dépense période actuelle
- `share` : % du total actuel
- `previousAmount` : dépense période précédente
- `amountChange` : variation en % (positif = hausse, négatif = baisse)
  - `amountChange: 100` → nouveau fournisseur (previousAmount = 0)
  - `amountChange: -100` → fournisseur disparu (amount = 0)

Sur le résumé (`summary.previousPeriod`) :
- `period.from/to` : dates de la période de comparaison
- `totalAmount` : total de la période précédente
- `amountChange` : variation globale en %

## Étape 3 — Résoudre les noms fournisseurs

```json
{ "companyId": "...", "ids": ["id1", "id2", "id3", ...] }
```

Joindre par ID : `{ ...row, name: suppliers.find(s => s.id === row.key)?.name || row.key }`

## Étape 4 — Identifier les anomalies

Alerter l'utilisateur sur :
- `amountChange > 500%` → croissance explosive (nouveau contrat, erreur de saisie ?)
- `amountChange < -50%` → forte baisse (résiliation, fin de projet ?)
- `previousAmount = 0` ET `amount > seuil` → nouveau fournisseur significatif
- "Others" en forte hausse → fragmentation du portefeuille fournisseurs

## Exemple live (données réelles, juil. 2025 → juin 2026 vs juil. 2024 → juin 2025)

Résumé :
- Période actuelle : **16 524 574,27 EUR** (7 199 payables)
- Période précédente : 17 108 631,54 EUR (5 804 payables)
- **Variation globale : -3,4%** (légère baisse)

Anomalies notables :
- Fournisseur `0qryRtMyYW` : +92 078% (424 EUR → 391 345 EUR) — quasi-nouveau
- Fournisseur `lt1euqhnunby1f` : +361,5% (131 938 EUR → 608 940 EUR) — forte croissance
- Fournisseur `9MCGQweUWi` : -68,3% (3 001 938 EUR → 951 166 EUR) — forte baisse
- Fournisseur `8xs-s358mod4ps` : nouveau (previousAmount=0), 738 607 EUR
- "Others" : +53,2% (portefeuille fournisseurs en expansion)

## Exemple de prompt

- "Quels sont nos 10 plus gros fournisseurs cette année vs l'année dernière ?" → groupBy=supplier, compareWithPreviousPeriod=true, limit=10 + resolve noms
- "Y a-t-il des fournisseurs qui ont explosé en dépense ?" → filtre amountChange > 200%
- "Nouveaux fournisseurs significatifs cette année ?" → filter previousAmount=0 AND amount > seuil