---
name: s04-analyze-spend-periode-longue
scenario: S04
description: Analyser les dépenses sur une période > 366 jours — pattern de découpage en sous-périodes et combinaison
tags: [spend-analysis, period, multi-year, pagination, limit]
when_to_use: Quand on veut une analyse de dépenses sur plus d'un an (rapport annuel, tendance pluriannuelle)
risk: P1 — spendesk_analyze_spend rejette toute période > 366 jours avec une erreur explicite. Nécessite de découper et combiner manuellement.
---

# Instructions — Analyse de dépenses sur période longue (> 1 an)

## ⚠️ Limite stricte : 366 jours maximum

`spendesk_analyze_spend` retourne une erreur explicite si la période dépasse 366 jours :
```
"fromDate must be on or before toDate, and the range cannot exceed 366 days."
```

**Solution** : découper en sous-périodes ≤ 366 jours, appeler séparément, combiner les résultats.

## ⚠️ Deuxième gotcha : limit=10 par défaut

Sur un groupBy=month sur 12 mois, les 2 derniers mois (les moins importants) sont agrégés dans une row "Others".
→ Toujours passer `limit: 12` pour une analyse annuelle complète par mois.
→ Pour 2 ans : combiner deux appels avec `limit: 12` chacun.

## Étape 1 — Calculer les sous-périodes

Règle : chaque sous-période ≤ 365 jours (laisser 1 jour de marge).

Exemples :
- Analyse 2024 : fromDate=2024-01-01, toDate=2024-12-31 ✅ (365 jours)
- Analyse 2025 : fromDate=2025-01-01, toDate=2025-12-31 ✅ (364 jours)
- Analyse 2026 YTD : fromDate=2026-01-01, toDate=2026-07-06 ✅ (186 jours)

## Étape 2 — Appeler chaque sous-période (en parallèle si possible)

Pour chaque sous-période :
```json
{
  "companyId": "...",
  "fromDate": "YYYY-MM-DD",
  "toDate": "YYYY-MM-DD",
  "groupBy": ["month"],
  "limit": 12
}
```

## Étape 3 — Combiner les résultats

**Ne combiner qu'après avoir tous les résultats** (ne pas présenter une vue partielle).

Agrégation :
- `totalAmount` : sommer les `summary.totalAmount.amount` de chaque sous-période (même devise fonctionnelle)
- `totalCount` : sommer les `summary.totalCount`
- Rows par mois : concaténer les arrays `data[]` des deux appels (pas de doublons — périodes distinctes)

⚠️ Si une sous-période contient une row "Others" : le breakdown par mois est **partiel** pour cette période. Augmenter `limit` ou restreindre la période.

## Étape 4 — Comparaison entre années

Pour comparer 2024 vs 2025 :
- Appel 1 : fromDate=2024-01-01, toDate=2024-12-31
- Appel 2 : fromDate=2025-01-01, toDate=2025-12-31
- Variation = (totalAmount_2025 - totalAmount_2024) / totalAmount_2024 × 100

Alternative : utiliser `compareWithPreviousPeriod=true` sur une période ≤ 366 jours (compare automatiquement avec la période précédente équivalente).

## Exemple live (données réelles ce compte)

| Période | Total (EUR) | Nb payables |
|---------|-------------|-------------|
| 2025 (Jan-Déc) | 17 916 500,61 EUR | 6 359 |
| 2026 (Jan-Juin) | 8 174 523,65 EUR | 3 937 |

Note : dans les résultats 2025, `limit=10` par défaut → mai et sept. (les 2 moins importants) tombaient en "Others". Avec `limit=12`, tous les mois sont visibles.

## Exemple de prompt

- "Analyse nos dépenses sur les 2 dernières années" → 2 appels année par année
- "Rapport de dépenses 2024 vs 2025" → 2 appels + comparaison
- "Tendance mensuelle depuis janvier 2024" → découper en 2 périodes + limit=12