# 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//` (~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//` + ses tests. - Conventions de champs dates: - Dans ce projet, ne pas introduire de `fields.DateTime`. - Utiliser `fields.Date` pour les dates metier et les champs de suivi UI, sauf demande explicite deja existante dans le module cible. - 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. - Pour les templates `stock.shipment.in`, preferer aussi des proprietes `report_*` sur le shipment plutot que des contextes ad hoc (`si_*`) quand le document devient metier ou client-specifique. - 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. - Pour les templates shipment, ne pas supposer qu'une variable locale comme `shipment` sera definie partout dans Genshi, surtout dans les headers/footers; preferer `records[0]....` ou des placeholders alignes sur le scope reel du report. - 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()`. - Rappels session templates (2026-04-08): - `insurance.fodt`: le texte "insured for account of" doit afficher la compagnie courante (shipment.company.party), pas le client. - `insurance.fodt`: exposer des proprietes Python `report_*` sur `stock.shipment.in` pour les montants (incoming moves) et les zones client-specifiques. - `insurance.fodt`: "Amount insured" suit la regle metier 110% du montant incoming (base calculee via lot -> purchase.line.unit_price * quantite courante convertie). - `insurance.fodt`: zone "Contact the following surveyor" alimentee par une propriete dediee, avec champ `surveyor` (party.party) cote shipment. - `packing_list.fodt`: date en haut a droite = date du jour; unites Net/Gross = unite de `purchase.line`. - `bill.fodt` (sale): la 2eme date doit etre une vraie maturity date (depuis `invoice.lines_to_pay.maturity_date`), pas `payment_term.rec_name`. - `bill.fodt` (sale): le montant en lettres doit provenir du montant du bill (facture/total), pas du `unit_price` de ligne. - Quand un template affiche les placeholders en brut, verifier que les champs sont bien des placeholders Relatorio dans le XML (pas du texte litteral). - Eviter les apostrophes echappees style `\'` dans placeholders; preferer `"` et `'`. ## 4.bis) Memo templates de session - Voir aussi `notes/template_business_rules.md` pour le recap detaille (business rules + decisions templates de la session). ## 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//tests/test_module.py` - `modules//tests/test_scenario.py` - `modules//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).