tradon/AGENTS.md

AGENTS.md

Guide rapide pour les agents qui codent dans ce repository.

1) Contexte du projet

• Codebase Tryton monolithique (coeur + modules metier).
• Noyau serveur a la racine: application.py, wsgi.py, admin.py, worker.py, cron.py.
• Couches framework importantes:
  • ORM: model/
  • Meta/systeme (ir): ir/
  • Protocoles RPC: protocols/
  • Backend DB: backend/
• Modules metier: modules/<module_name>/ (~220 modules).

2) Regles de travail pour agent

• Ne jamais toucher des fichiers sans rapport avec la demande.
• Limiter le scope de modif au minimum necessaire.
• Respecter le style existant du module cible.
• Ne pas supprimer du code legacy sans verifier les usages.
• Si comportement incertain: preferer un patch conservateur + test.

3) Zones de bruit a ignorer pendant l'exploration

• .venv/
• __pycache__/
• build/ (quand present dans des sous-modules)
• Fichiers temporaires editeur (ex: *.swp)

4) Comment choisir ou coder selon le besoin

• Si bug ORM/champs:
  • Lire model/fields/*.py et les tests tests/test_field_*.py.
• Si bug transaction/DB:
  • Lire transaction.py, backend/*/database.py, tests/test_backend.py.
• Si bug API/RPC/HTTP:
  • Lire wsgi.py, rpc.py, protocols/*, tests/test_rpc.py, tests/test_wsgi.py.
• Si bug metier:
  • Modifier uniquement modules/<module>/ + ses tests.
• Si bug template Relatorio (.fodt):
  • Lire d'abord le template standard voisin du meme domaine (invoice.fodt, sale.fodt, etc.).
  • Preferer des proprietes Python simples exposees par le modele plutot que des expressions Genshi complexes dans le template.
  • Dans les placeholders XML, utiliser " et ' plutot que des antislashs type \'.
  • Si un document facture depend fortement d'une vente/achat, ajouter au besoin un petit pont Python pour exposer des report_* stables au template.
  • Si plusieurs actions de report pointent vers report_name = 'account.invoice', verifier aussi le cache invoice_report_cache dans modules/account_invoice/invoice.py: un mauvais cache peut faire croire que plusieurs actions utilisent le meme .fodt.
  • Avant de conclure qu'un template ou une action est faux, verifier si le report alternatif doit bypasser le cache standard.
  • Dans purchase_trade, pour remonter d'une facture vers shipment, pro forma, freight ou autres donnees logistiques, privilegier le lot physique comme pont entre purchase.line, sale.line et shipment.
  • Pour FREIGHT VALUE, ne pas lire un champ direct sur la facture: retrouver le fee de shipment (shipment_in) dont le produit est Maritime freight, puis utiliser fee.get_amount().

5) Workflow de modification (obligatoire)

1. Identifier le module et le flux impacte.
2. Localiser un test existant proche du comportement a changer.
3. Implementer le plus petit patch possible.
4. Ajouter/adapter les tests au plus pres du changement.
5. Lancer la validation ciblee (pas toute la suite si inutile).
6. Donner un resume du risque residuel.

6) Checklist avant de rendre une modif

• Le changement est-il limite au domaine demande ?
• Le comportement existant non cible est-il preserve ?
• Les droits/regles (ir.rule, acces) sont-ils impactes ?
• Les vues XML et labels sont-ils coherents si un champ change ?
• Les tests modifies couvrent-ils le bug/la feature ?
• Le message de commit (si demande) explique clairement le pourquoi ?

7) Tests: point de depart pratique

• Suite coeur: tests/test_tryton.py
• Tests coeur par domaine: tests/test_*.py
• Tests module:
  • modules/<module>/tests/test_module.py
  • modules/<module>/tests/test_scenario.py
  • modules/<module>/tests/scenario_*.rst

Quand possible, lancer d'abord la cible minimale:

• fichier de test touche
• puis fichier voisin de regression
• puis suite plus large uniquement si necessaire

8) Contrat de sortie attendu de l'agent

Toujours fournir:

• Liste des fichiers modifies
• Resume fonctionnel (ce qui change)
• Resume technique (pourquoi ce design)
• Tests executes + resultat
• Risques residuels et impacts potentiels

9) Cas sensibles (demander confirmation humaine)

• Changement schema/structure de donnees
• Changement de logique de securite/acces
• Changement de comportement transverse (transaction, pool, RPC, worker)
• Refactor multi-modules sans ticket explicite

10) Raccourci de demarrage pour agent

1. Lire ce fichier.
2. Lire le(s) fichier(s) touche(s) et leurs tests.
3. Proposer le patch minimal.
4. Implementer + tester cible.
5. Rendre avec le contrat de sortie (section 8).