tradon/modules/purchase/AGENTS.md

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.