Créer, annuler ou clôturer un bon de commande

# Cycle de vie des bons de commande

## ⚠️ Outils d'écriture en Beta, dont deux irréversibles

`create_purchase_order`, `cancel_purchase_order` et `close_purchase_order` demandent la permission « Manage purchase orders », désactivée par défaut : un Admin ou Account Owner l'active sur la connexion, puis l'utilisateur se reconnecte et la coche.

| Action | Réversible ? |
|--------|--------------|
| Créer | Non supprimable. Seul recours : annuler, tant qu'il est ouvert et sans facture |
| Annuler | **Irréversible** |
| Clôturer | **Irréversible**, et le montant est réécrit |

Un bon de commande ne se supprime jamais. Un statut terminal (`closed` ou `cancelled`) ne peut pas passer à l'autre.

## Créer un bon de commande

### 1. Résoudre le fournisseur et le centre de coûts

```json
{ "tool": "get_suppliers", "params": { "search": "<nom du fournisseur>" } }
```

Passer `supplierId` dès qu'un fournisseur correspond. `supplierName` crée un fournisseur à la volée si le nom ne correspond pas exactement : « Acme Corp. » face à « Acme Corp » crée un **second fournisseur** et scinde l'historique.

```json
{ "tool": "get_cost_centers", "params": {} }
```

`costCenterId` est obligatoire.

### 2. Confirmer avec l'utilisateur, puis créer

Rappeler le fournisseur, le montant, le centre de coûts et la période, et attendre l'accord.

```json
{
  "tool": "create_purchase_order",
  "params": {
    "supplierId": "<id>",
    "amount":    { "amount": 12000, "currency": "EUR", "precision": 2 },
    "netAmount": { "amount": 10000, "currency": "EUR", "precision": 2 },
    "costCenterId": "<id>",
    "startDate": "2026-10-05", "endDate": "2026-10-31",
    "customFieldAssociations": [],
    "description": "…"
  }
}
```

- Les montants sont en **unités mineures** de la devise fonctionnelle : `12000` = EUR 120,00. `amount` est TTC, `netAmount` HT, et `amount` ≥ `netAmount`.
- `customFieldAssociations` est obligatoire : passer `[]` s'il n'y en a pas.
- Réponse observée : `purchaseOrderId` et `purchaseOrderNumber` (« PO-20 »).

⚠️ Deux points vérifiés en direct :
- **Le bon de commande est ouvert immédiatement** (`status: open`, `billingStatus: waitingForBilling`) : la création par cet outil ne passe par aucune étape d'approbation visible. Le dire à l'utilisateur avant de créer.
- **L'outil n'est pas idempotent** : un second appel crée un second bon de commande. Si le résultat est incertain (délai dépassé), vérifier avec `get_purchase_orders` avant de recommencer.

## Annuler un bon de commande

### 1. Vérifier qu'il est annulable

```json
{ "tool": "get_purchase_orders", "params": { "status": ["open"], "supplierIds": ["<id>"] } }
```

Annulable seulement s'il est `open`, **sans facture rattachée** (`invoices: []`) et **sans dépense associée**.

### 2. Nommer le bon de commande et obtenir un accord explicite

Donner son numéro, son fournisseur (résoudre `supplierId` en nom) et son montant, rappeler que c'est irréversible, attendre l'accord. La vérification des données ne vaut pas accord.

```json
{ "tool": "cancel_purchase_order", "params": { "purchaseOrderId": "<id>" } }
```

Réponse observée : `{ "outcome": "cancelled", … }`. Le bon de commande reste visible avec `status: cancelled` ; à la relecture, il ne porte plus `billingStatus` ni `costCenterId`.

Un second appel sur le même bon de commande renvoie une erreur explicite (« the purchase order is not in open status ») : c'est une réponse, pas un échec à relancer.

## Clôturer un bon de commande

Possible seulement s'il est `open`, avec **au moins une facture rattachée et toutes les factures payées**.

```json
{ "tool": "close_purchase_order", "params": { "purchaseOrderId": "<id>" } }
```

⚠️ **Clôturer réécrit `amount` avec le montant facturé.** Le budget approuvé à l'origine n'est plus lisible ensuite : un bon de commande approuvé à 10 000 et facturé 8 000 affichera 8 000. Si l'utilisateur a besoin de garder la trace du montant approuvé, le relever avant de clôturer. La clôture peut aussi échouer côté engagement de dépense : lire le motif plutôt que réessayer.

## Limites à dire

- `amount − billedAmount` ne révèle jamais un dépassement : `get_purchase_orders` ne permet pas de répondre à « quels bons de commande ont dépassé leur budget ».
- Un bon de commande reste `open` après sa date de fin : rien ne le ferme automatiquement.
- Le MCP ne peut pas approuver une demande de bon de commande ni payer une facture.

## Ce qui a été testé

Testé en direct sur le compte démo le 5 octobre 2026 : création du bon de commande PO-20 (EUR 120,00 TTC, fournisseur existant), relecture à l'état ouvert, annulation, relecture à l'état annulé, et second appel d'annulation pour observer l'erreur. **La clôture n'a pas été exécutée** (elle demande un bon de commande avec des factures payées) ; elle est décrite d'après la documentation de l'outil.

## Exemples de prompts utilisateur

- "Crée un bon de commande de 12 000 € TTC pour Accenture sur le centre de coûts Tech, du 1er novembre au 31 janvier"
- "Annule le bon de commande PO-20, il a été créé par erreur"
- "Quels bons de commande ouverts sont entièrement facturés et payés, et peuvent être clôturés ?"