25.03.26

modules/purchase/AGENTS.md

@@ -0,0 +1,105 @@
+# 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.