# Invariants structurants

Statut: `migration partielle`

Ces invariants doivent etre relus avant de modifier des flux `purchase_trade`
touchant lots, quantites, fees, PnL, factures ou templates.

## INV-PT-001 - Le lot physique est le pont metier stable

### Regle consultant

Quand une information doit relier achat, vente, shipment et facture, le chemin
fonctionnel de reference passe par le lot physique. Il porte le lien entre les
contrats et l'execution logistique.

### Notes developpeur

- Source historique: `BR-PT-002`.
- Voir aussi: [lots-and-quantities.md](lots-and-quantities.md),
  [matching.md](matching.md), [reports-templates.md](reports-templates.md).
- Champs frequents: `lot.line`, `lot.sale_line`, `lot_shipment_in`,
  `lot_shipment_internal`, `lot_shipment_out`.

## INV-PT-002 - Le reliquat ouvert ne doit pas doubler les lots physiques

### Regle consultant

Une quantite deja executee physiquement ne doit pas rester disponible comme
quantite ouverte. Le reliquat ouvert represente seulement ce qui reste a
executer.

### Notes developpeur

- Source historique: `BR-PT-020`.
- Le calcul doit tenir compte de la quantite contractuelle, des lots physiques
  existants et des `lot.qt` deja matches ou shippes.
- Regle de conservation:
  `sum(lots physiques) + lot virtuel = quantity_theorical`.
- Regle du forecast ouvert minimal:
  `sum(lot.qt non zero) >= max(lot virtuel, 0)`.
- Un surplus de forecast ouvert est accepte apres surconsommation physique:
  `lot.qt` s'arrete a zero, alors que le lot virtuel absorbe toute la quantite
  physique.
- Les lignes `lot.qt` a zero sont ignorees par les checks: elles peuvent servir
  de memoire d'une prevision consommee.
- Le check applicatif est centralise dans
  `lot.lot.assert_lines_quantity_consistency()`.
- Le diagnostic SQL correspondant est
  [sql/quantity_consistency_checks.sql](sql/quantity_consistency_checks.sql).

## INV-PT-003 - Les fees utilisent leurs lots effectifs

### Regle consultant

Un fee ouvert suit le lot virtuel tant qu'il n'y a pas de lot physique. Des
qu'un ou plusieurs lots physiques sont lies au fee, ils deviennent la base
effective de calcul.

### Notes developpeur

- Source historique: `BR-PT-021`.
- Ne pas supprimer le lien virtuel: il reste le fallback si les physiques sont
  retires.
- Voir [fees.md](fees.md).

## INV-PT-004 - Les templates doivent rester simples

### Regle consultant

Les documents doivent afficher des informations metier stables, meme si le
chemin technique pour les retrouver est complexe.

### Notes developpeur

- Preferer des proprietes Python `report_*` aux expressions Genshi complexes.
- Ne pas supposer qu'une variable locale comme `shipment` existe partout dans
  un `.fodt`.
- Voir [reports-templates.md](reports-templates.md).
