Achats fournisseurs

Périmètre : devis fournisseurs (avec lignes de détail), inbox d'ingestion IA (OCR PDF → relecture humaine → commit), comparateur multi-devis, commandes fournisseurs (PO), réception → création d'assets, factures fournisseurs et rapprochement 3 voies, plus la boucle achats↔leasing (capital financé depuis devis retenu, commande auto à la signature de contrat, indicateur coût réel vs financé).

Vocabulaire & entités

Les totaux (totalHt, totalVat, totalTtc) sont toujours recalculés serveur à partir des lignes (RG-13-01). Les champs stockés sont dénormalisés pour le tri/perf, jamais source de vérité.

Écrans

Modèle de données (points clés)

• Lignes de détail : 3 modèles iso-convention côté client — SupplierQuoteLine, SupplierOrderLine, SupplierInvoiceLine. Chaque ligne porte position, designation, quantity, unitPriceHt, vatRatePct, discountPct, ecoTaxHt, lineTotalHt (calculé), assetModelId?.
• Traçabilité : SupplierOrderLine.sourceQuoteLineId → ligne de devis source ; SupplierInvoiceLine.sourceOrderLineId → ligne de commande source (base du rapprochement 3 voies RG-13-12).
• Inbox IA : SupplierDocumentImport avec fileId (PDF), detectedType (enum QUOTE|INVOICE|CREDIT_NOTE|ORDER|UNKNOWN), status (enum EXTRACTING|NEEDS_REVIEW|COMMITTED|DISCARDED|ERROR), rawExtraction: Json?, matchedSupplierId?. Unicité par [organizationId, fileId] (idempotence RG-13-04).
• Boucle leasing : LeaseAffairSupplierQuote (N:N, isRetained). LeaseFinancing étendu avec capitalSource: CapitalSource (MANUAL|SUPPLIER_QUOTE) et sourceSupplierQuoteId?. SupplierOrder étendu avec leaseContractId? et leaseAffairId?.
• Migration zero-downtime : colonnes nullables ajoutées en migration additive ; backfill des anciens documents sans lignes via prisma/backfill/13-supplier-lines-reprise.ts (ligne unique designation="Reprise — montant global").

API

Toutes les routes exigent les permissions purchasing.* ou les permissions existantes du domaine concerné.

Les lignes utilisent un PUT « set complet » (remplacement transactionnel de toutes les lignes + recalcul des totaux) plutôt qu'un CRUD ligne à ligne — cohérent avec une grille éditable UI, évite les désynchros de totaux.

Exemple de référence d'endpoint :

curl -s -X POST "$API/api/workspace/lease-financings/$FIN_ID/capital-from-quote" \
  -H "Content-Type: application/json" -H "Cookie: $SESSION" \
  -d '{"supplierQuoteId":"sqt_...","mode":"preview"}'

{
  "capitalHt": 18500,
  "previousCapitalHt": 15000,
  "periodicPmtHt": 412.50,
  "previousPeriodicPmtHt": 338.20,
  "totalInterestHt": 1450,
  "deltaPmtPct": 22.0
}

Workflows

Inbox OCR IA (ingestion Scaleway pixtral-12b)

Dépôt PDF (1..N)
  → upload S3 + hash SHA-256 (idempotence RG-13-04)
  → SupplierDocumentImport { status: EXTRACTING }
  → job IA (purchase-document-extract) :
      détection type + extraction en-tête + lignes
      match SIRET → Supplier existant ou "Créer via Pappers"
  → status: NEEDS_REVIEW (ou ERROR si budget IA épuisé RG-13-05)
  → relecture humaine (form pré-rempli)
  → POST /commit { type, supplierId, documentNumber, lines[] }
  → SupplierQuote | SupplierInvoice créé + lignes
  → status: COMMITTED

L'IA propose, l'humain valide — aucune création automatique sans passage par NEEDS_REVIEW (RG-13-03). Si le budget mensuel est épuisé, l'import passe ERROR et la saisie manuelle reste disponible.

Comparateur multi-devis et capital LLD

LeaseAffair
  → POST /quotes  (rattacher ≥ 1 devis)
  → GET  /quote-comparison  (tableau lignes comparées, moins-disant surligné)
  → POST /quotes/[id]/retain  (isRetained=true, dé-retient l'ancien RG-13-07)
  → POST /lease-financings/[id]/capital-from-quote { mode:"preview" }
      ↓ aperçu PMT recalculé
  → POST ...capital-from-quote { mode:"apply" }
      ↓ capitalHt = Σ lignes HT, capitalSource=SUPPLIER_QUOTE

Commande automatique à la signature de contrat

LeaseContract → signature
  → onContractSigned() (hook service)
  → generateFromRetainedQuote(orgId, contractId)
      ↓ copie lignes du devis retenu
      ↓ SupplierOrder { status: DRAFT, leaseContractId, leaseAffairId }
  [idempotent : 1 seul PO auto/contrat, re-signature sans effet RG-13-09]
  → Confirmation manuelle + envoi fournisseur (action "validate-and-send")

Réception → création d'assets

SupplierOrder { status: CONFIRMED }
  → POST /receive { lines: [{ orderLineId, receivedQuantity, serialNumbers? }] }
  → pour chaque ligne reçue :
      Asset { acquisitionAmountHt=unitPriceHt, leaseContractId, modelId=assetModelId }
  → SupplierOrderLine.receivedQuantity cumulé (≤ quantity commandée RG-13-11)
  → SupplierOrder.status → RECEIVED | PARTIALLY_RECEIVED

Rapprochement 3 voies facture↔commande↔réception

SupplierInvoice + lignes (via inbox OCR ou saisie)
  → GET /match-lines
      ↓ écart par ligne via sourceOrderLineId → sourceQuoteLineId
      tolérance 5 % → OK | MISMATCH
  → MISMATCH → blocage validation (override ADMIN avec motif obligatoire, audit)
  → POST /allocate-contract { leaseContractId }
      ↓ SupplierInvoiceAllocation (≤ totalHt facture RG-13-13)
      ↓ indicateur "coût réel vs financé" mis à jour sur le contrat

Règles métier

• RG-13-01 — Totaux totalHt/totalVat/totalTtc toujours recalculés serveur à partir des lignes. Jamais saisis.
• RG-13-02 — lineTotalHt = round2(quantity × unitPriceHt × (1 − discountPct/100)) + ecoTaxHt. Arrondi ROUND_HALF_UP 2 décimales (cohérent server/lib/finance.ts:roundCents).
• RG-13-03 — Aucune création d'entité réelle sans validation humaine explicite (passage NEEDS_REVIEW → commit). L'IA ne crée jamais en aveugle.
• RG-13-04 — SupplierDocumentImport idempotent par hash fichier (File.checksumSha256) par organisation : redéposer le même PDF réutilise l'import existant non-DISCARDED.
• RG-13-05 — Extraction IA bloquée si isAiBudgetExhausted() → import ERROR, message explicite, saisie manuelle disponible.
• RG-13-06 — Un devis n'est rattachable qu'à une affaire de la même organisation.
• RG-13-07 — Au plus 1 devis isRetained=true par LeaseAffair. Retenir un nouveau devis dé-retient l'ancien (transaction).
• RG-13-08 — Capital depuis devis exige capitalSource=SUPPLIER_QUOTE. Modification manuelle ultérieure repasse capitalSource=MANUAL (avec sourceSupplierQuoteId conservé pour audit).
• RG-13-09/10 — Génération de commande à la signature : idempotente (1 seul PO auto par contrat), statut DRAFT, envoi au fournisseur toujours manuel.
• RG-13-11 — Assets créés à la réception (jamais à la signature). Réception partielle cumulable, jamais au-delà de la quantité commandée.
• RG-13-12 — Rapprochement 3 voies au niveau ligne via sourceOrderLineId. Écart > 5 % → MISMATCH, bloquant sauf override ADMIN (motif + audit).
• RG-13-13 — Allocation facture → contrat ne dépasse jamais le totalHt de la facture.
• RG-13-14 — Type UNKNOWN détecté : l'écran de relecture s'ouvre mais l'utilisateur doit choisir le type avant le commit.

Codes d'erreur métier