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.
• 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/<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).

• Rappels session 2026-04-09:
  • invoice_ict.fodt / invoice_ict_final.fodt: poids et unites depuis lot.qt.hist / lot_unit_line, priorite lots physic, sinon lot virtual unique.
  • invoice_ict.fodt / invoice_ict_final.fodt: infos shipment depuis les lots reels des lignes facture; ne rien afficher si plusieurs shipments differents.
  • invoice_ict.fodt / invoice_ict_final.fodt: S/I = shipment.reference; NB BALES: 0 => Unchanged sur le final.
  • invoice_ict.fodt / invoice_ict_final.fodt: quantites uniformisees a 2 decimales; conversion LBS via UoM, jamais via un facteur fixe aveugle.
  • invoice_ict.fodt / invoice_ict_final.fodt: si plusieurs lignes reutilisent le meme lot, les lignes detaillees suivent la quantite facturee convertie, mais le GROSS global doit rester le vrai delta historique du lot.
  • sale_ict.fodt: meme priorite lots; les mots suivent l'unite reelle; le total convertit vers une unite commune, qui est celle du lot virtuel seulement s'il y a un seul lot virtuel sur tout le report.
  • lot.report.r_del_period: utiliser sale.line.del_period pour lot_s sans lot_p, sinon purchase.line.del_period.
  • lot.do_weighing: lot_qt editable et ecrasement direct de lot.lot_qt.
  • account.invoice: Validate cree aussi le account.move pour les factures client; Post ne doit plus forcer une fresh session sur ce flux.
  • pricing.pricing: saisie manuelle autorisee meme sans composant; eod_price non editable et calcule en prix moyen pondere; last=True gere par groupe line + component, choisi sur la pricing_date la plus grande.
  • purchase_trade: trader filtre sur TRADER, operator sur OPERATOR; fallback sur quantity si quantity_theorical est vide dans les quotas/pricings.
  • sale.line / purchase.line: en mode basis, sans price_component, le Price et le Fix. progress de la ligne doivent remonter depuis la ligne Summary sans component.