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.