# AGENTS.md - Module `purchase`

Ce guide complete le `AGENTS.md` racine.
Pour ce module, les regles locales ci-dessous priment.

## 1) Perimetre metier

Le module `purchase` gere le cycle d'achat fournisseur:

- commande d'achat (`purchase.purchase`, `purchase.line`)
- facturation fournisseur (`account.invoice` liee a l'achat)
- reception/retour de stock (`stock.move`, `stock.shipment.in`, `stock.shipment.in.return`)
- reporting achats (axes temporels, fournisseur, produit)

## 2) Fichiers pivots

- Logique coeur:
  - `modules/purchase/purchase.py`
- Extensions metier connexes:
  - `modules/purchase/product.py`
  - `modules/purchase/stock.py`
  - `modules/purchase/invoice.py`
  - `modules/purchase/party.py`
  - `modules/purchase/configuration.py`
  - `modules/purchase/purchase_reporting.py`
- Vues et actions:
  - `modules/purchase/purchase.xml`
  - `modules/purchase/stock.xml`
  - `modules/purchase/invoice.xml`
  - `modules/purchase/purchase_reporting.xml`
- Manifest et dependances:
  - `modules/purchase/tryton.cfg`
- Documentation metier:
  - `modules/purchase/docs/business-rules.template.md` (template)
  - `modules/purchase/docs/business-rules.md` (instance a remplir)

## 3) Etats et flux critiques a preserver

Workflow de commande (dans `purchase.py`):

- `draft -> quotation -> confirmed -> processing -> done`
- transitions de retour existent aussi (`cancelled`, retour a `draft`, etc.)

Invariants importants:

- `invoice_state` et `shipment_state` doivent rester coherents apres `process()`.
- `process()` orchestre facture + stock + recalcul d'etats, ne pas contourner sans raison.
- `delete()` exige une commande annulee.
- Les methodes `create_invoice()` et `create_move()` sont sensibles (gestion `lots` et `action`).

## 4) Couplages a surveiller

- Facture:
  - `purchase.py` <-> `invoice.py`
  - gestion des exceptions facture (`purchase_exception_state`)
- Stock:
  - `purchase.py` <-> `stock.py`
  - liens `moves`, expeditions entrantes, retours
- Produit/fournisseur/prix:
  - `product.py` impacte prix d'achat, UoM, fournisseurs
- Tiers:
  - `party.py` impacte adresses/parametres fournisseur et contraintes d'effacement

## 5) Convention de modification pour ce module

1. Modifier d'abord le coeur minimal dans `purchase.py` ou le fichier specialise adequat.
2. Mettre a jour XML uniquement si comportement UI/action change.
3. Si regle metier impactee, mettre a jour `docs/business-rules.md`.
4. Ajouter un test proche du flux reel (scenario `.rst` prioritaire si possible).
5. Verifier les impacts transverses facture/stock avant rendu.

## 6) Strategie de test recommandee

Priorite 1 (rapide):

- `modules/purchase/tests/test_module.py`

Priorite 2 (comportement metier):

- `modules/purchase/tests/test_scenario.py`
- Scenarios cibles selon la modif:
  - `scenario_purchase.rst`
  - `scenario_purchase_manual_invoice.rst`
  - `scenario_purchase_line_cancelled.rst`
  - `scenario_purchase_line_cancelled_on_shipment.rst`
  - `scenario_purchase_return_wizard.rst`
  - `scenario_purchase_reporting.rst`

Si la modif touche prix/UoM/fournisseur:

- ajouter un cas dans `test_module.py` ou un scenario dedie.

## 7) Cas qui exigent validation humaine

- Changement du workflow d'etats
- Changement des regles de creation facture/mouvement
- Changement de logique sur retours fournisseur
- Changement qui altere les ecritures comptables ou le statut de paiement

## 8) Definition of done (module `purchase`)

- Le flux metier cible fonctionne de bout en bout.
- Les etats `state`, `invoice_state`, `shipment_state` restent coherents.
- Les tests du module pertinents passent.
- Le patch est limite aux fichiers necessaires.