# Structure documentaire Markdown - purchase_trade

Document recapitulatif de la structure mise en place pour les regles metier, bugs, backlogs et gestion documentaire.

Objectif general. La documentation est organisee pour separer les regles metier, les bugs, les backlogs d'implementation et les conventions de gestion. L'objectif est de garder un contexte lisible pour les humains et chargeable a la demande pour les agents.

## 1. Arborescence Markdown

modules/purchase_trade/docs/ business-rules.md documentation-management.md bugs.md template-rules.md business rules/ lot-quantity.md lot-navigation.md invoice-freight.md market-price-import.md backlog/ market-price-import-backlog.md

## 2. Role et description des fichiers

Fichier | Role | Description
--- | --- | ---
`business-rules.md` | Catalogue des regles metier | Point d'entree des regles `purchase_trade`. Contient le scope, le glossaire, le catalogue des IDs `BR-PT-xxx` et les liens vers les fiches detaillees.
`documentation-management.md` | Regles de gestion documentaire | Decrit le workflow: creation de regles, questions ouvertes `Q:`/`A:`, backlogs, bugs, statuts, commits de reference et discipline de scope.
`bugs.md` | Registre des bugs | Lieu d'enregistrement initial des bugs avec ID stable `BUG-PT-xxx`. Chaque bug doit etre relie a une entree backlog.
`template-rules.md` | Regles specifiques aux templates | Guide de correction et d'analyse des templates Relatorio/FODT, notamment les ponts Python, les placeholders XML et le cache des reports facture.
`business rules/lot-quantity.md` | Regle detaillee BR-PT-001 | Specifie l'ajustement de `quantity_theorical`, la synchronisation du lot virtuel et des quantites ouvertes `lot.qt`.
`business rules/lot-navigation.md` | Regle detaillee BR-PT-002 | Documente le lot physique comme pont stable entre purchase, sale, shipment et facture.
`business rules/invoice-freight.md` | Regle detaillee BR-PT-003 | Definit que le `FREIGHT VALUE` des factures vient du fee de shipment `Maritime freight`, via le lot physique.
`business rules/market-price-import.md` | Regle detaillee BR-PT-004 | Specifie l'import de prix marche depuis Excel: colonnes attendues, parsing, creation d'index, resultats, edge cases et questions tranchees.
`backlog/market-price-import-backlog.md` | Backlog feature Market Price Import | Liste les travaux issus de BR-PT-004 et des bugs associes, avec statut, priorite, source, impact code, tests attendus et commit d'implementation si applicable.

## 3. Workflow recommande

### Nouvelle regle metier

- Ajouter une ligne dans `business-rules.md`.
- Creer une fiche dediee dans `business rules/` si la regle a des impacts code, tests, edge cases ou questions.
- Utiliser des questions `Q:` et reponses `A:`; ajouter `Comment:` si la decision implique un changement code.

### Nouveau bug

- Creer une entree dans `bugs.md` avec un ID stable `BUG-PT-xxx`.
- Creer une entree backlog correspondante, soit dans un backlog existant, soit dans un nouveau fichier sous `backlog/`.
- Lier le bug au backlog et le backlog au bug.

### Implementation

- Passer le backlog de `open` a `in-progress`, puis `to-be-tested` apres implementation.
- Documenter le travail realise et le statut de validation.
- Apres commit, enregistrer le hash du commit dans l'entree backlog.

## 4. Avantages

- Traçabilite. Les decisions metier, bugs, backlogs, tests et commits sont relies.
- Scope clair. Un agent peut charger seulement le fichier pertinent au lieu de tout lire.
- Meilleure maintenance. Les regles lourdes vivent dans des fiches dediees; le catalogue reste court.
- Priorisation explicite. Le backlog garde statut, priorite, tests attendus et validation.
- Historique de decision. Les sections `Open Questions` gardent les arbitrages `Q:`/`A:`.
- Support bug propre. Chaque bug a un ID stable et une entree backlog obligatoire.

## 5. Inconvenients / points de vigilance

- Discipline necessaire. Il faut maintenir les liens et les statuts, sinon la structure perd de sa valeur.
- Risque de fragmentation. Trop de petits fichiers peuvent ralentir la comprehension si le catalogue n'est pas tenu a jour.
- Noms avec espaces. Le dossier `business rules/` est lisible, mais les liens Markdown doivent utiliser `business%20rules` dans les URLs.
- Backlog a synchroniser. Une correction code doit etre reportee dans le backlog, notamment le statut et le commit.
- Duplication possible. Certaines informations peuvent apparaitre dans regle, bug et backlog; il faut garder chaque fichier dans son role.

## 6. Estimation de consommation tokens

Estimation basee sur la regle pratique de l'image fournie: 1 KB ≈ 200 tokens.

Fichier | Taille approx. | Tokens approx. | Usage conseille
--- | --- | --- | ---
`backlog/market-price-import-backlog.md` | 4.70 KB | ~939 | Charger pour prioriser ou coder un item Market Price Import.
`bugs.md` | 1.67 KB | ~333 | Charger au moment de declarer ou suivre un bug.
`business rules/invoice-freight.md` | 1.49 KB | ~298 | Charger pour les sujets freight/facture.
`business rules/lot-navigation.md` | 1.84 KB | ~369 | Charger pour les chemins achat/vente/shipment.
`business rules/lot-quantity.md` | 2.87 KB | ~574 | Charger pour les changements de quantite theorique.
`business rules/market-price-import.md` | 6.21 KB | ~1 242 | Charger pour comprendre la specification complete de l'import.
`business-rules.md` | 2.21 KB | ~441 | Charger comme index de depart.
`documentation-management.md` | 4.47 KB | ~893 | Charger quand on gere docs, bugs, statuts ou backlog.
`template-rules.md` | 6.14 KB | ~1 227 | Charger uniquement pour les sujets templates/reporting.
Total des 9 fichiers | 31.58 KB | ~6 316 | Faible a modere si charge ensemble; meilleur en chargement a la demande.

### Evaluation

Consommation estimee: faible a moderee. A environ 6 300 tokens pour tout le dossier Markdown `purchase_trade/docs`, la structure reste tres raisonnable par rapport a un budget conseille de 60k-80k tokens. Le risque principal n'est pas un fichier unique, mais l'accumulation avec l'historique de conversation, les diffs, les logs et les sorties de tests.
Bonne pratique. Charger `business-rules.md` comme index, puis seulement la fiche detaillee, le bug ou le backlog utile. Eviter de charger tous les fichiers docs plus de gros logs ou des diffs complets dans la meme interaction.

## 7. Recommandation finale

La structure est pertinente et peu couteuse en tokens si elle est utilisee comme une documentation modulaire. Elle donne une bonne base pour travailler avec des agents: contexte court au depart, approfondissement a la demande, liens explicites entre bug, regle, backlog, tests et commit.

Document genere le 2026-05-08 pour le module `purchase_trade`.