Suivi du statut de paiement des factures

# Suivi du statut de paiement des factures

## But

Donner une vue claire et instantanée des factures selon leur avancement dans le cycle de paiement : approuvées mais non encore exportées, planifiées pour paiement, exportées, réglées. Cas d'usage typique : **cash flow planning quotidien**, vérification avant export comptable, ou réponse à "où en est la facture de [fournisseur] ?"

---

## Périmètre MCP — ce qui est visible

> ⚠️ Le MCP Spendesk donne accès aux factures **à partir du stade "approuvé"**. Les factures encore en cours de validation (inbox, review, pending_approval) ne sont pas accessibles.

| Stade | Accessible ? | Via quel outil |
|-------|:----------:|---------------|
| Soumise / en attente d'approbation | ❌ | Non disponible dans le MCP |
| **Approuvée — en attente de paiement** | ✅ | `get_payables` (status=approved) |
| **Échue — paiement dû** | ✅ | `spendesk_get_due_invoices` |
| **Exportée / planifiée** | ✅ | `get_payables` (status=exported/scheduled) |
| **Réglée** | ✅ | `get_settlements` |

---

## Instructions

### Étape 1 — Identifier la question précise

Déterminer ce que l'utilisateur veut :
- **Vue globale** : toutes les factures en attente de paiement → aller à l'Étape 2
- **Statut d'une facture précise** : facture d'un fournisseur spécifique → aller à l'Étape 3
- **Cash flow** : factures approuvées à payer aujourd'hui/cette semaine → aller à l'Étape 4
- **Vérification export** : quelles factures ont déjà été exportées → aller à l'Étape 5

---

### Étape 2 — Vue globale des factures en attente de paiement

```
Appelle get_payables avec :
  - limit: 50 (maximum recommandé pour éviter les timeouts)
  - Si possible, filtrer par status pour ne récupérer que les factures post-approbation

Pour chaque facture retournée, noter :
  - id, supplierName (ou supplierId → résoudre via get_supplier_by_id si nécessaire)
  - amount + currency
  - status (approved / scheduled / exported / paid)
  - dueDate ou paymentDate si disponible
  - createdAt

Ensuite appelle spendesk_get_due_invoices pour récupérer les factures dont le paiement est échu.

Construire un tableau récapitulatif groupé par statut :
```

**Format de réponse attendu :**

```
📋 Factures en attente de paiement — [date du jour]

✅ APPROUVÉES — EN ATTENTE D'EXPORT ([N] factures, [total] €)
┌─────────────────────┬──────────┬──────────┬─────────────┐
│ Fournisseur         │ Montant  │ Statut   │ Date        │
├─────────────────────┼──────────┼──────────┼─────────────┤
│ Fournisseur A       │ X,XXX €  │ approved │ JJ/MM/AAAA  │
│ Fournisseur B       │ X,XXX €  │ approved │ JJ/MM/AAAA  │
└─────────────────────┴──────────┴──────────┴─────────────┘

⏰ ÉCHUES — PAIEMENT EN RETARD ([N] factures, [total] €)
[liste des factures dont la date d'échéance est dépassée]

📤 PLANIFIÉES / EN COURS ([N] factures, [total] €)
[liste des factures avec payment scheduled ou processing]
```

---

### Étape 3 — Statut d'une facture fournisseur précise

```
Utilise get_payables avec un filtre sur le nom du fournisseur ou le montant.
Si tu as un supplierId, utilise-le directement.
Si tu as seulement le nom, appelle d'abord get_suppliers pour trouver l'ID.

Retourne le détail complet de la facture :
```

**Format de réponse attendu :**

```
📄 Facture [Fournisseur] — Statut détaillé

Fournisseur : [nom]
Montant : [X,XXX €]
Date de création : [JJ/MM/AAAA]
Date d'échéance : [JJ/MM/AAAA] (ou "non renseignée")
Statut actuel : [statut]

📍 Position dans le cycle :
[Soumise] → [En approbation] → ✅ [Approuvée] → [Planifiée] → [Exportée] → [Réglée]
                                     ↑ position actuelle

ℹ️ [Explication du statut en langage clair]
```

---

### Étape 4 — Cash flow : factures approuvées à payer

**Cas d'usage Bragi** — skill à lancer quotidiennement pour alimenter le cash flow planning.

```
1. Appelle get_payables pour récupérer toutes les factures approuvées
   - Limite : 50 par appel (si tu penses avoir plus de 50 factures, fais plusieurs appels
     avec des filtres de date pour segmenter)
   - Trier par dueDate ou montant

2. Appelle spendesk_get_due_invoices pour identifier les factures échues en priorité

3. Si tu as besoin de comparer avec la veille (mode delta) :
   - Compare les IDs retournés aujourd'hui avec ceux du dernier run
   - "Nouvelles" = dans la liste aujourd'hui mais pas hier
   - "Sorties" = dans la liste hier mais plus aujourd'hui (= exportées/payées)

Construire le rapport cash flow :
```

**Format de réponse attendu :**

```
💰 Cash flow — Factures à payer — [date du jour]

🆕 NOUVELLES factures approuvées depuis hier : [N]
[liste avec montant et fournisseur]

📤 TOTAL à payer aujourd'hui :
• Factures échues : [N] — [total] €  ← payer en priorité
• Factures approuvées (non échues) : [N] — [total] €
• TOTAL GLOBAL : [N] factures — [TOTAL] €

✅ SORTIES depuis hier (exportées/payées) : [N] factures — [total] €

---
💡 Conseil : [ex. "3 factures Stripe échues depuis +7j — à traiter en priorité"]
```

---

### Étape 5 — Vérification avant export comptable

```
1. Appelle get_settlements pour récupérer les règlements récents (dernières 48h ou depuis la
   dernière clôture)
2. Appelle get_payables pour croiser avec les factures "exported" ou "paid"
3. Identifier les factures approuvées NON encore dans les settlements = à exporter

Construire la checklist :
```

**Format de réponse attendu :**

```
✅ Vérification export — [date]

DÉJÀ EXPORTÉES/RÉGLÉES : [N] factures
[liste rapide : fournisseur + montant + date règlement]

🔴 APPROUVÉES MAIS PAS ENCORE EXPORTÉES : [N] factures
[liste : fournisseur + montant + date approbation]
→ Ces factures sont prêtes à exporter vers votre outil comptable.

⚠️ HORS PÉRIMÈTRE MCP (factures en cours d'approbation) :
Le MCP ne voit pas les factures encore en validation — consultez Spendesk directement
pour les factures en inbox/review.
```

---

## Limitations importantes à communiquer

1. **Factures pré-approbation invisibles** — Si l'utilisateur cherche une facture récemment soumise mais pas encore approuvée, elle n'apparaîtra pas dans les résultats MCP. Le dire explicitement.

2. **Limite 50 factures par appel** — En fin de mois avec beaucoup de factures, segmenter par période (semaine par semaine) pour rester sous la limite.

3. **Approbation depuis Claude impossible** (pour l'instant) — Si l'utilisateur demande d'approuver une facture, expliquer que les opérations d'écriture arrivent en Q3 2026.

---

## Exemples de prompts

- "Quelles factures sont approuvées et en attente de paiement ?"
- "Où en est la facture de [fournisseur] ?"
- "Montre-moi les factures à payer cette semaine pour mon cash flow"
- "Quelles factures ont été réglées depuis lundi ?"
- "Y a-t-il des factures échues non encore payées ?"
- "Nouvelles factures approuvées depuis hier ?" (mode delta — skill automatisé)