# 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 `&quot;` et `&apos;` 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()`.

## 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).