@mostajs/achats 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,32 @@
1
+ # Changelog — @mostajs/achats
2
+
3
+ **Auteur** : Dr Hamid MADANI <drmdh@msn.com>
4
+ Format : Keep a Changelog ; versions : SemVer.
5
+
6
+ ## [0.1.1] — 2026-11-22
7
+
8
+ ### Ajouté
9
+ - Trois exemples publiés, exécutables **depuis le paquet installé, sans autre module** (ils n'importent que `@mostajs/achats` et `node:*`) : `exemples/01-quantite-proposee.mjs`, `exemples/02-cycle-commande.mjs`, `exemples/03-reprise-apres-panne.mjs`, et le lanceur `exemples/tous.mjs`. Cités dans le README et `llms.txt`.
10
+ - Essais T-ACH-23 à T-ACH-26 : chaque exemple tourne dans le dépôt, puis depuis le paquet fabriqué par `npm pack` et installé hors ligne dans un projet vierge ; l'exemple d'intégration tourne et n'est pas publié.
11
+ - Scripts `npm run exemples` et `npm run exemple:integration`.
12
+
13
+ ### Corrigé
14
+ - La 0.1.0 publiait `exemples/reapprovisionner.mjs`, qui importe `@mostajs/stocks`, `@mostajs/fournisseurs` et `@mostajs/numbering` — des dépendances de développement : installé, il ne pouvait pas tourner. Il devient `integration/reapprovisionner.mjs`, dans le dépôt seulement (le script `npm run exemple` devient `npm run exemple:integration`).
15
+
16
+ ### Inchangé
17
+ - Aucune API : `src/` ne change que par la version du manifeste de `register()`.
18
+
19
+ ## [0.1.0] — 2026-11-18
20
+
21
+ ### Ajouté
22
+ - `creerAchats({ depots, stock?, fournisseurs?, numeroter?, horloge?, id?, reglages? })` : `creer`, `modifier`, `envoyer`, `recevoir`, `reprendreEntrees`, `solder`, `annuler`, `lire`, `lister`, `receptionsDe`, `aReprendre`, `enCommande`, `proposer`, `brouillonsDepuis`.
23
+ - Cycle de vie `brouillon → envoyee → recue_partiellement → soldee`, et `annulee` (`ETATS`, `TRANSITIONS`), historique tracé dans la commande.
24
+ - Réception partielle, excédent refusé par défaut (sans écriture) ou accepté, refus sur une commande soldée, annulée ou en brouillon ; entrée en stock ligne par ligne par le port `stock.entrer`, reprise après panne sans double entrée (`cle` par ligne).
25
+ - Version optimiste sur la commande : deux réceptions simultanées ne s'additionnent pas (`CONFLIT_VERSION`).
26
+ - `calculerQuantite` : point de commande, stock de sécurité (en unités ou en jours), couverture, arrondi au colis et au minimum, en entiers.
27
+ - Adaptateurs `portStocks` (`@mostajs/stocks` 0.5.0) et `portNumerotation` (`@mostajs/numbering` 0.1.1) ; `@mostajs/fournisseurs` 0.2.0 se branche tel quel.
28
+ - `depotMemoire()` (contrat à prédicat avec version), `schemaCommandeAchat`, `schemaReceptionAchat`, `register(registry)` (`@mostajs/achats/register`).
29
+ - Permissions contribuées `achats:lire`, `achats:proposer`, `achats:commander`, `achats:envoyer`, `achats:recevoir`, `achats:cloturer` et `PERMISSION_PAR_OPERATION` ; aucune attribution à un rôle.
30
+ - 23 codes d'erreur (`ErreurAchats`, `CODES`, `LIBELLES`).
31
+ - Exemple de vérification `exemples/reapprovisionner.mjs`, sur les vrais `stocks`, `fournisseurs` et `numbering`.
32
+ - 22 essais `T-ACH-n` (`@mostajs/mjs-unit`).
package/LICENSE ADDED
@@ -0,0 +1,15 @@
1
+ @mostajs/offline-replay
2
+ Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
3
+
4
+ This program is free software: you can redistribute it and/or modify it under
5
+ the terms of the GNU Affero General Public License as published by the Free
6
+ Software Foundation, either version 3 of the License, or (at your option) any
7
+ later version.
8
+
9
+ This program is distributed in the hope that it will be useful, but WITHOUT
10
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11
+ FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
12
+ details.
13
+
14
+ You should have received a copy of the GNU Affero General Public License
15
+ along with this program. If not, see <https://www.gnu.org/licenses/agpl-3.0.html>.
package/README.md CHANGED
@@ -1,3 +1,144 @@
1
- # Temporary Holding Version
1
+ # @mostajs/achats
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Auteur** : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · N1 · aucune dépendance d'exécution · Node ≥ 20
4
+
5
+ Ce module gère les **commandes fournisseurs**. Il propose la quantité à commander, suit chaque commande jusqu'à sa réception, partielle ou totale, et fait entrer en stock ce qui est reçu.
6
+
7
+ - **Cycle de vie** : `brouillon → envoyee → recue_partiellement → soldee`, et `annulee`. Chaque passage est tracé dans la commande (qui, quand, d'où, vers où, pourquoi).
8
+ - **Quantité proposée** : point de commande (demande pendant le délai + stock de sécurité), niveau cible (couverture), arrondi au colis et au minimum de commande. Tout est calculé en entiers.
9
+ - **Réception** : une ou plusieurs livraisons par commande, ligne par ligne. L'excédent est refusé par défaut et peut être accepté. Une commande soldée ou annulée ne reçoit plus rien.
10
+ - **Entrée en stock** par un port injecté. Si le stock tombe en panne au milieu d'une livraison, `reprendreEntrees` termine le travail sans entrer deux fois la même ligne.
11
+
12
+ Le module ne recode ni le stock, ni le référentiel des fournisseurs, ni la numérotation. Il compose `@mostajs/stocks`, `@mostajs/fournisseurs` et `@mostajs/numbering` par injection, et il n'en dépend pas à l'exécution.
13
+
14
+ ## Installer
15
+
16
+ ```bash
17
+ npm install @mostajs/achats
18
+ ```
19
+
20
+ | Entrée | Contenu |
21
+ |---|---|
22
+ | `@mostajs/achats` | `creerAchats`, `calculerQuantite`, `depotMemoire`, `portStocks`, `portNumerotation`, `ETATS`, `TRANSITIONS`, `CODES`, `LIBELLES`, `ErreurAchats`, `PERMISSIONS`, `PERMISSION_PAR_OPERATION`, `schemaCommandeAchat`, `schemaReceptionAchat` |
23
+ | `@mostajs/achats/register` | `register(registry)` : manifeste, permissions et schémas, pour `@mostajs/socle` |
24
+
25
+ ## En 20 lignes
26
+
27
+ ```js
28
+ import { createStocks } from '@mostajs/stocks';
29
+ import { creerFournisseurs } from '@mostajs/fournisseurs';
30
+ import { createNumbering } from '@mostajs/numbering';
31
+ import { creerAchats, portStocks, portNumerotation } from '@mostajs/achats';
32
+
33
+ const numbering = createNumbering({ store }); // séquence définie par l'application
34
+ numbering.define({ name: 'commande-achat', format: '[BC]-YYYY-NNNN', resetEvery: 'year' });
35
+
36
+ const achats = creerAchats({
37
+ depots: { commandes: magasin.repo('achats_commandes'), receptions: magasin.repo('achats_receptions') },
38
+ stock: portStocks(createStocks({ repositories })), // entrer, disponible, consommation
39
+ fournisseurs: creerFournisseurs({ depot, depotReferences }), // branché tel quel
40
+ numeroter: portNumerotation(numbering),
41
+ });
42
+
43
+ const propositions = await achats.proposer({ articles: [{ articleId, delaiJours: 7, stockSecurite: 10, prixUnitaire: 1250 }] });
44
+ const { brouillons } = await achats.brouillonsDepuis(propositions, { par: utilisateur.id }); // à valider par un humain
45
+ const commande = await achats.envoyer(brouillons[0].id, { par: utilisateur.id }); // numéro tiré ici
46
+ await achats.recevoir(commande.id, { par: magasinier.id, lignes: [{ ligne: 1, quantite: 3 }] }); // → recue_partiellement
47
+ ```
48
+
49
+ ## Exemples
50
+
51
+ Publiés dans le paquet, ils tournent **depuis le paquet installé, sans autre module** : chacun n'importe que `@mostajs/achats` et `node:*`, écrit ses ports (stock, fournisseurs, numérotation) en quelques lignes, et se vérifie lui-même (code de sortie 0).
52
+
53
+ | Exemple | Ce qu'il montre |
54
+ |---|---|
55
+ | `exemples/01-quantite-proposee.mjs` | `calculerQuantite` : point de commande, position avec l'en-commande, sécurité en jours, minimum de commande, refus d'une donnée invalide |
56
+ | `exemples/02-cycle-commande.mjs` | proposer, brouillon, envoyer (numéro tiré), recevoir en deux fois (excédent refusé puis accepté), solder avec motif, annuler |
57
+ | `exemples/03-reprise-apres-panne.mjs` | panne du stock au milieu d'une livraison, `aReprendre`, `reprendreEntrees` sans double entrée |
58
+ | `exemples/tous.mjs` | les lance tous |
59
+
60
+ ```bash
61
+ node node_modules/@mostajs/achats/exemples/tous.mjs # depuis une application qui a installé le paquet
62
+ npm run exemples # depuis le dépôt
63
+ ```
64
+
65
+ L'exemple d'**intégration** sur les vrais `@mostajs/stocks`, `@mostajs/fournisseurs` et `@mostajs/numbering` reste dans le dépôt, hors du paquet (il a besoin de ces trois modules) : `npm run exemple:integration` (`integration/reapprovisionner.mjs`).
66
+
67
+ ## La quantité proposée
68
+
69
+ Les calculs sont faits en entiers. La consommation est une quantité observée sur une fenêtre (`fenetreJours`, 30 par défaut), et chaque division est arrondie à l'entier supérieur.
70
+
71
+ | Grandeur | Calcul |
72
+ |---|---|
73
+ | demande pendant le délai | ⌈ consommé × délai / fenêtre ⌉ |
74
+ | stock de sécurité | donné en unités, ou ⌈ consommé × jours de sécurité / fenêtre ⌉ |
75
+ | point de commande | demande pendant le délai + stock de sécurité |
76
+ | position | disponible + reste en commande (commandes envoyées et reçues en partie) |
77
+ | déclenché | position ≤ point de commande |
78
+ | niveau cible | point de commande + ⌈ consommé × couverture / fenêtre ⌉ (couverture : 30 jours par défaut) |
79
+ | quantité | niveau cible − position, au moins un colis, arrondie au colis, au moins le minimum |
80
+
81
+ `proposer` rend aussi `enBrouillon` : ce qui figure déjà dans un brouillon n'est pas « en commande », mais il faut le voir pour ne pas commander deux fois.
82
+
83
+ ## La réception, dans l'ordre
84
+
85
+ 1. **L'état** : la commande doit être `envoyee` ou `recue_partiellement`. Sinon le module lève `COMMANDE_NON_ENVOYEE`, `COMMANDE_SOLDEE` ou `COMMANDE_ANNULEE`.
86
+ 2. **Les lignes** : chaque ligne reçue désigne une ligne de la commande, par son numéro ou par son article (`LIGNE_INCONNUE`, `LIGNE_EN_DOUBLE`), avec une quantité entière positive (`QUANTITE_INVALIDE`).
87
+ 3. **L'excédent** : en mode `excedent: 'refuser'` (le défaut), le module lève `RECEPTION_EXCEDENTAIRE` avec le reste et le reçu de chaque ligne en cause, et n'écrit rien. En mode `'accepter'`, l'excédent est enregistré, entre en stock au prix de la commande et est rendu dans `excedents`.
88
+ 4. **La commande** est écrite sous version : deux réceptions simultanées donnent `CONFLIT_VERSION` à la seconde, qui n'entre rien en stock.
89
+ 5. **Le stock** : chaque ligne appelle `stock.entrer` avec la quantité multipliée par `parColis`, le montant (quantité × prix unitaire), `ref = 'achat:<numéro>'` et `cle = '<réception>:<ligne>'`.
90
+ 6. **La panne** : si une entrée échoue, le module lève `ENTREE_STOCK_ECHOUEE` avec `details.receptionId`. `reprendreEntrees(receptionId)` entre les lignes restantes, et elles seules.
91
+
92
+ ## Le dépôt
93
+
94
+ Un dépôt par entité, au contrat à prédicat de `@mostajs/repository` :
95
+
96
+ ```
97
+ create(doc) → doc · findById(id) → doc | null · find(predicat) → doc[] · update(id, patch, { version }?) → doc | null
98
+ ```
99
+
100
+ `update` doit rendre `null` si la version stockée n'est pas celle qui est passée. En base, cela s'écrit `UPDATE … WHERE id = ? AND version = ?`. `depotMemoire()` tient ce contrat (copies isolées), pour les essais et les démonstrations. Les tables `achats_commandes` et `achats_receptions` sont déclarées par `register()`.
101
+
102
+ ## Les permissions
103
+
104
+ Le module **contribue** six permissions et n'en attribue aucune à un rôle : c'est l'administrateur qui les coche dans la matrice. Il ne les vérifie pas non plus. L'application consulte `PERMISSION_PAR_OPERATION` et vérifie le droit avant d'appeler l'opération.
105
+
106
+ | Permission | Opérations |
107
+ |---|---|
108
+ | `achats:lire` | `lire`, `lister`, `receptionsDe`, `aReprendre`, `enCommande` |
109
+ | `achats:proposer` | `proposer` |
110
+ | `achats:commander` | `creer`, `modifier`, `brouillonsDepuis` |
111
+ | `achats:envoyer` | `envoyer` |
112
+ | `achats:recevoir` | `recevoir`, `reprendreEntrees` |
113
+ | `achats:cloturer` | `solder`, `annuler` |
114
+
115
+ ## Réglages
116
+
117
+ | Réglage | Défaut | Rôle |
118
+ |---|---|---|
119
+ | `excedent` | `'refuser'` | politique d'excédent à la réception (`'refuser'` ou `'accepter'`) ; l'appel peut la changer |
120
+ | `fenetreJours` | 30 | fenêtre de consommation observée ; un article peut la changer |
121
+ | `couvertureJours` | 30 | jours couverts au-delà du point de commande ; un article peut la changer |
122
+
123
+ `reglages` est un objet ou une fonction, relue à chaque appel. Les valeurs viennent des Paramètres de l'application.
124
+
125
+ ## Ce qu'il ne fait pas
126
+
127
+ | Ne fait pas | Qui le fait |
128
+ |---|---|
129
+ | mouvements, niveaux, seuils, valorisation | `@mostajs/stocks` |
130
+ | référentiel des fournisseurs, références code ↔ matière | `@mostajs/fournisseurs` |
131
+ | facture d'achat, écritures comptables | `@mostajs/compta` |
132
+ | numérotation | `@mostajs/numbering` |
133
+ | recherche d'offres, comparaison de prix | `@mostajs/sourcing` |
134
+ | bon de commande en PDF, envoi par courriel | `@mostajs/file-export`, `@mostajs/mailer` |
135
+ | attribution des permissions | `@mostajs/rbac`, par l'administrateur |
136
+ | écrans | l'application |
137
+
138
+ ## Essais
139
+
140
+ ```bash
141
+ npm test # 26 essais T-ACH-n (@mostajs/mjs-unit), sans base ni réseau, dont les exemples lancés depuis le paquet packé
142
+ npm run exemples # les exemples publiés
143
+ npm run exemple:integration # l'exemple sur les vrais stocks, fournisseurs et numbering (dépôt seulement)
144
+ ```
@@ -0,0 +1,31 @@
1
+ // @mostajs/achats — exemple 1 : la quantité proposée au point de commande (fonction pure, en entiers).
2
+ // Ne demande rien d'autre que le paquet. Lancer : node exemples/01-quantite-proposee.mjs (code 0 = vérifié)
3
+ // @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
4
+ import assert from 'node:assert/strict';
5
+ import { calculerQuantite, ErreurAchats } from '@mostajs/achats';
6
+
7
+ // Un entrepôt : 30 cartons disponibles, 90 consommés sur 30 jours (3 par jour), livrés en 7 jours, par colis de 25.
8
+ const base = { disponible: 30, consommation: { quantite: 90, jours: 30 }, delaiJours: 7, stockSecurite: 10, couvertureJours: 30, multiple: 25 };
9
+
10
+ // 1. Point de commande = demande pendant le délai (3 × 7 = 21) + stock de sécurité (10) = 31 ; 30 ≤ 31 : déclenché.
11
+ // Niveau cible = 31 + 3 × 30 = 121 ; brute = 121 − 30 = 91 ; arrondie au colis de 25 → 100 (4 colis).
12
+ const q = calculerQuantite(base);
13
+ console.log(`déclenché ${q.declenche} : point ${q.pointDeCommande}, cible ${q.niveauCible}, brute ${q.quantiteBrute} → ${q.quantite} (${q.colis} colis)`);
14
+ assert.deepEqual(
15
+ [q.declenche, q.demandePendantDelai, q.stockSecurite, q.pointDeCommande, q.niveauCible, q.quantiteBrute, q.quantite, q.colis],
16
+ [true, 21, 10, 31, 121, 91, 100, 4],
17
+ );
18
+
19
+ // 2. Ce qui est déjà en commande compte dans la position : 30 + 50 = 80 > 31, rien à commander.
20
+ const enCours = calculerQuantite({ ...base, enCommande: 50 });
21
+ console.log(`avec 50 en commande : position ${enCours.position}, déclenché ${enCours.declenche}, quantité ${enCours.quantite}`);
22
+ assert.deepEqual([enCours.position, enCours.declenche, enCours.quantite], [80, false, 0]);
23
+
24
+ // 3. Stock de sécurité en jours (5 jours × 3 = 15) et minimum de commande (150 unités) : 136 brut → 150 (6 colis).
25
+ const m = calculerQuantite({ ...base, stockSecurite: undefined, stockSecuriteJours: 5, minimumQuantite: 150 });
26
+ console.log(`sécurité en jours ${m.stockSecurite}, point ${m.pointDeCommande}, brute ${m.quantiteBrute} → ${m.quantite} (${m.colis} colis)`);
27
+ assert.deepEqual([m.stockSecurite, m.pointDeCommande, m.niveauCible, m.quantiteBrute, m.quantite, m.colis], [15, 36, 126, 96, 150, 6]);
28
+
29
+ // 4. Une donnée invalide est refusée par un code, jamais arrondie en silence.
30
+ assert.throws(() => calculerQuantite({ ...base, disponible: 2.5 }), (e) => e instanceof ErreurAchats && e.code === 'DONNEES_INVALIDES');
31
+ console.log('✓ exemple 1 vérifié');
@@ -0,0 +1,74 @@
1
+ // @mostajs/achats — exemple 2 : le cycle d'une commande fournisseur, de la proposition à la clôture.
2
+ // Les ports (stock, fournisseurs, numérotation) sont écrits ici en quelques lignes : le paquet seul suffit.
3
+ // En production, on branche @mostajs/stocks (portStocks), @mostajs/fournisseurs et @mostajs/numbering (portNumerotation).
4
+ // Lancer : node exemples/02-cycle-commande.mjs (code 0 = vérifié)
5
+ // @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
6
+ import assert from 'node:assert/strict';
7
+ import { creerAchats, depotMemoire, PERMISSION_PAR_OPERATION } from '@mostajs/achats';
8
+
9
+ const JOUR = 86400e3;
10
+ let t = Date.UTC(2026, 10, 2, 8);
11
+ const horloge = () => t;
12
+
13
+ // Port stock : un niveau disponible, une consommation observée, et le journal des entrées.
14
+ const entrees = [];
15
+ const stock = {
16
+ async disponible(articleId) { return articleId === 'carton-40' ? 30 : 0; },
17
+ async consommation() { return 90; }, // 90 sur la fenêtre de 30 jours
18
+ async entrer(e) { entrees.push(e); return { id: `mvt-${entrees.length}` }; },
19
+ };
20
+ // Port fournisseurs : une fiche et une référence au colis de 25 (forme de @mostajs/fournisseurs).
21
+ const fournisseurs = {
22
+ async parId(id) { return id === 'F1' ? { id, nom: 'CARTONNERIE EXEMPLE', actif: true } : null; },
23
+ async fournisseursPourMatiere(articleId) {
24
+ return articleId === 'carton-40' ? [{ fournisseurId: 'F1', code: 'CT-40', parColis: 25, libelle: 'Carton 40x30x30 (25)' }] : [];
25
+ },
26
+ };
27
+ // Port de numérotation : sans trou, tiré à l'envoi seulement.
28
+ let n = 0;
29
+ const numeroter = () => `BC-2026-${String(++n).padStart(4, '0')}`;
30
+
31
+ const achats = creerAchats({ depots: { commandes: depotMemoire(), receptions: depotMemoire() }, stock, fournisseurs, numeroter, horloge });
32
+
33
+ // 1. Proposer (ne crée rien), puis un brouillon par fournisseur, à valider par une personne.
34
+ console.log(`droit à vérifier par l'application avant « proposer » : ${PERMISSION_PAR_OPERATION.proposer}`);
35
+ const [p] = await achats.proposer({ articles: [{ articleId: 'carton-40', delaiJours: 7, stockSecurite: 10, prixUnitaire: 1250 }] });
36
+ console.log(`proposé : ${p.colis} colis de ${p.parColis} chez ${p.fournisseurId}`);
37
+ assert.deepEqual([p.declenche, p.fournisseurId, p.colis, p.quantite], [true, 'F1', 4, 100]);
38
+ const { brouillons } = await achats.brouillonsDepuis([p], { par: 'acheteur' });
39
+ assert.equal(brouillons[0].etat, 'brouillon');
40
+ assert.equal(brouillons[0].numero, null, 'le numéro n\'est tiré qu\'à l\'envoi');
41
+
42
+ // 2. Envoyer : le numéro est tiré.
43
+ const a = await achats.envoyer(brouillons[0].id, { par: 'acheteur' });
44
+ console.log(`envoyée : ${a.numero}, ${a.lignes[0].quantite} colis, total ${a.total}`);
45
+ assert.deepEqual([a.etat, a.numero, a.total], ['envoyee', 'BC-2026-0001', 5000]);
46
+
47
+ // 3. Recevoir en deux livraisons : 3 colis, puis un excédent refusé (rien n'est écrit), puis accepté.
48
+ t += 5 * JOUR;
49
+ const r1 = await achats.recevoir(a.id, { par: 'magasin', bonLivraison: 'BL-1', lignes: [{ ligne: 1, quantite: 3 }] });
50
+ console.log(`livraison 1 : ${r1.commande.etat}, reste ${r1.reliquats[0].reste} colis`);
51
+ assert.equal(r1.commande.etat, 'recue_partiellement');
52
+ await assert.rejects(achats.recevoir(a.id, { par: 'magasin', lignes: [{ ligne: 1, quantite: 2 }] }), (e) => e.code === 'RECEPTION_EXCEDENTAIRE');
53
+ assert.equal(entrees.length, 1, 'le refus n\'a rien entré en stock');
54
+ const r2 = await achats.recevoir(a.id, { par: 'magasin', bonLivraison: 'BL-2', excedent: 'accepter', lignes: [{ ligne: 1, quantite: 2 }] });
55
+ console.log(`livraison 2 : ${r2.commande.etat}, excédent accepté ${r2.excedents[0].excedent} colis`);
56
+ assert.equal(r2.commande.etat, 'soldee');
57
+ assert.deepEqual(entrees.map((e) => [e.quantite, e.montant, e.ref]), [[75, 3750, 'achat:BC-2026-0001'], [50, 2500, 'achat:BC-2026-0001']]);
58
+
59
+ // 4. Une deuxième commande, reçue en partie puis soldée avec un motif : le reliquat est abandonné et tracé.
60
+ const b = await achats.envoyer((await achats.creer({ fournisseurId: 'F1', par: 'acheteur', lignes: [{ articleId: 'carton-40', quantite: 4, prixUnitaire: 1250 }] })).id, { par: 'acheteur' });
61
+ await achats.recevoir(b.id, { par: 'magasin', lignes: [{ ligne: 1, quantite: 1 }] });
62
+ assert.equal(await achats.enCommande('carton-40'), 75, 'reste en commande : 3 colis de 25');
63
+ const bs = await achats.solder(b.id, { par: 'acheteur', motif: 'fin de série chez le fournisseur' });
64
+ console.log(`${bs.numero} : ${bs.etat} (${bs.motifCloture})`);
65
+ assert.equal(bs.etat, 'soldee');
66
+ assert.equal(await achats.enCommande('carton-40'), 0);
67
+
68
+ // 5. Une troisième, annulée avant l'envoi : aucun numéro consommé.
69
+ const c = await achats.creer({ fournisseurId: 'F1', par: 'acheteur', lignes: [{ articleId: 'carton-40', quantite: 2, prixUnitaire: 1250 }] });
70
+ const ca = await achats.annuler(c.id, { par: 'acheteur', motif: 'doublon' });
71
+ assert.deepEqual([ca.etat, ca.numero], ['annulee', null]);
72
+ await assert.rejects(achats.recevoir(c.id, { par: 'magasin', lignes: [{ ligne: 1, quantite: 1 }] }), (e) => e.code === 'COMMANDE_ANNULEE');
73
+ console.log(`états : ${(await achats.lister()).map((x) => `${x.numero ?? '(sans numéro)'} ${x.etat}`).join(' · ')}`);
74
+ console.log('✓ exemple 2 vérifié');
@@ -0,0 +1,56 @@
1
+ // @mostajs/achats — exemple 3 : le stock tombe en panne au milieu d'une livraison ; la reprise termine le travail
2
+ // sans entrer deux fois la même ligne (clé `<réception>:<ligne>`). Le paquet seul suffit.
3
+ // Lancer : node exemples/03-reprise-apres-panne.mjs (code 0 = vérifié)
4
+ // @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
5
+ import assert from 'node:assert/strict';
6
+ import { creerAchats, depotMemoire, ErreurAchats } from '@mostajs/achats';
7
+
8
+ // Port stock qui échoue au deuxième appel tant qu'il est « en panne ».
9
+ const entrees = [];
10
+ let enPanne = true;
11
+ let appels = 0;
12
+ const stock = {
13
+ async entrer(e) {
14
+ appels += 1;
15
+ if (enPanne && appels === 2) throw new Error('stock indisponible');
16
+ entrees.push(e);
17
+ return { id: `mvt-${entrees.length}` };
18
+ },
19
+ async disponible() { return 0; },
20
+ async consommation() { return 0; },
21
+ };
22
+ let n = 0;
23
+ const achats = creerAchats({ depots: { commandes: depotMemoire(), receptions: depotMemoire() }, stock, numeroter: () => `BC-2026-${String(++n).padStart(4, '0')}` });
24
+
25
+ // Une commande de deux lignes, envoyée, puis reçue en entier.
26
+ const c = await achats.creer({ fournisseurId: 'F1', par: 'acheteur', lignes: [
27
+ { articleId: 'carton-40', quantite: 4, prixUnitaire: 1250, parColis: 25 },
28
+ { articleId: 'ruban-48', quantite: 10, prixUnitaire: 300 },
29
+ ] });
30
+ await achats.envoyer(c.id, { par: 'acheteur' });
31
+
32
+ // 1. La réception est enregistrée, la ligne 1 entre en stock, la ligne 2 échoue : erreur à code, avec la réception.
33
+ let receptionId = null;
34
+ await assert.rejects(achats.recevoir(c.id, { par: 'magasin', lignes: [{ ligne: 1, quantite: 4 }, { ligne: 2, quantite: 10 }] }), (e) => {
35
+ assert.ok(e instanceof ErreurAchats);
36
+ assert.equal(e.code, 'ENTREE_STOCK_ECHOUEE');
37
+ receptionId = e.details.receptionId;
38
+ return true;
39
+ });
40
+ console.log(`panne : réception ${receptionId} à reprendre, ${entrees.length} ligne entrée sur 2`);
41
+ assert.equal(entrees.length, 1);
42
+ assert.deepEqual((await achats.aReprendre()).map((r) => r.id), [receptionId]);
43
+
44
+ // 2. Le stock revient ; la reprise n'entre que la ligne manquante.
45
+ enPanne = false;
46
+ await achats.reprendreEntrees(receptionId);
47
+ console.log(`reprise : ${entrees.map((e) => `${e.articleId} ×${e.quantite} (clé ${e.cle})`).join(', ')}`);
48
+ assert.deepEqual(entrees.map((e) => [e.articleId, e.quantite]), [['carton-40', 100], ['ruban-48', 10]]);
49
+ assert.equal(new Set(entrees.map((e) => e.cle)).size, 2, 'aucune ligne entrée deux fois');
50
+ assert.deepEqual(await achats.aReprendre(), []);
51
+
52
+ // 3. Une seconde reprise ne fait rien de plus.
53
+ await achats.reprendreEntrees(receptionId);
54
+ assert.equal(entrees.length, 2);
55
+ assert.equal((await achats.lire(c.id)).etat, 'soldee');
56
+ console.log('✓ exemple 3 vérifié');
@@ -0,0 +1,19 @@
1
+ // @mostajs/achats — lance chaque exemple numéroté de ce dossier dans son propre processus et dit lesquels ont tenu.
2
+ // Lancer : node exemples/tous.mjs (ou npm run exemples dans le dépôt) — code 0 = tous vérifiés.
3
+ // @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
4
+ import { spawnSync } from 'node:child_process';
5
+ import { readdirSync } from 'node:fs';
6
+ import { dirname, join } from 'node:path';
7
+ import { fileURLToPath } from 'node:url';
8
+
9
+ const ici = dirname(fileURLToPath(import.meta.url));
10
+ const exemples = readdirSync(ici).filter((f) => /^\d{2}-.*\.mjs$/.test(f)).sort();
11
+ let echecs = 0;
12
+ for (const f of exemples) {
13
+ const r = spawnSync(process.execPath, [join(ici, f)], { encoding: 'utf8' });
14
+ const ok = r.status === 0;
15
+ if (!ok) echecs += 1;
16
+ console.log(`${ok ? '✓' : '✗'} ${f}${ok ? '' : `\n${r.stdout}${r.stderr}`}`);
17
+ }
18
+ console.log(echecs ? `✗ ${echecs} exemple(s) en échec sur ${exemples.length}` : `✓ ${exemples.length} exemples vérifiés`);
19
+ process.exit(echecs ? 1 : 0);
package/llms.txt ADDED
@@ -0,0 +1,105 @@
1
+ # @mostajs/achats 0.1.1 — fiche LLM
2
+ > Commandes fournisseurs (brouillon → envoyée → reçue en partie → soldée, et annulée), quantité proposée au point
3
+ > de commande avec stock de sécurité, réception partielle ou excédentaire qui entre en stock par un port injecté.
4
+
5
+ - Niveau: N1 générique, forme moteur · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
6
+ - Pile: mosta-gestion-stack · Zéro dépendance d'exécution · Node ≥ 20 (ou navigateur : structuredClone, crypto.randomUUID)
7
+
8
+ ## RÔLE
9
+ Répond à « que commander, à qui, et qu'en a-t-on reçu ? ». Porte la commande fournisseur et son état, calcule la
10
+ quantité à commander, enregistre les livraisons ligne par ligne et fait entrer en stock ce qui est reçu, par un port.
11
+ Ne recode ni le stock (@mostajs/stocks), ni le référentiel des fournisseurs (@mostajs/fournisseurs), ni la numérotation
12
+ (@mostajs/numbering) : il les COMPOSE par injection.
13
+
14
+ ## QUESTION
15
+ Que commander, à qui, et qu'en a-t-on reçu ?
16
+
17
+ ## API
18
+ - creerAchats({ depots: { commandes, receptions }, stock?, fournisseurs?, numeroter?, horloge?, id?, reglages? }) → service
19
+ (CONFIG_INVALIDE si un dépôt manque ou si un port porte autre chose que des fonctions)
20
+ creer({ fournisseurId, lignes: [{ articleId, quantite, prixUnitaire, code?, libelle?, parColis? }], reference?, note?, devise?, par })
21
+ → brouillon ; numero null ; code, libelle, parColis complétés par fournisseurs.fournisseursPourMatiere
22
+ modifier(id, { lignes?, reference?, note?, devise? }, { par }) brouillon seulement (COMMANDE_NON_MODIFIABLE)
23
+ envoyer(id, { par }) brouillon → envoyee ; numero = await numeroter({ type: 'commande-achat', le, fournisseurId })
24
+ recevoir(id, { lignes: [{ ligne | articleId, quantite, lot?, peremption? }], le?, bonLivraison?, excedent?, par })
25
+ → { commande, reception, excedents: [{ ligne, articleId, excedent }], reliquats: [{ ligne, articleId, reste }] }
26
+ reprendreEntrees(receptionId) après ENTREE_STOCK_ECHOUEE : entre les lignes restantes, elles seules
27
+ solder(id, { motif, par }) recue_partiellement → soldee (reliquat abandonné, tracé)
28
+ annuler(id, { motif, par }) brouillon | envoyee → annulee
29
+ lire(id) · lister({ etat?, fournisseurId?, articleId? }) · receptionsDe(id) · aReprendre() · enCommande(articleId)
30
+ proposer({ articles: [{ articleId, delaiJours, fournisseurId?, stockSecurite? | stockSecuriteJours?, couvertureJours?,
31
+ minimumQuantite?, parColis?, prixUnitaire?, fenetreJours? }] }) → propositions (ne crée rien)
32
+ brouillonsDepuis(propositions, { par }) → { brouillons (un par fournisseur), sansFournisseur: [articleId] }
33
+ - calculerQuantite({ disponible, enCommande?, consommation: { quantite, jours }, delaiJours, stockSecurite? | stockSecuriteJours?,
34
+ couvertureJours?, minimumQuantite?, multiple? })
35
+ → { declenche, position, demandePendantDelai, stockSecurite, pointDeCommande, niveauCible, quantiteBrute, multiple, quantite, colis }
36
+ - depotMemoire() · portStocks(stocks) · portNumerotation(numbering, { nom = 'commande-achat' })
37
+ - ETATS, TRANSITIONS, CODES, LIBELLES, ErreurAchats(code, message?, details?) { code, message, details }
38
+ - PERMISSIONS, PERMISSION_PAR_OPERATION · schemaCommandeAchat, schemaReceptionAchat
39
+ - '@mostajs/achats/register' → register(registry) : manifeste, permissions, schémas (CommandeAchat, ReceptionAchat)
40
+
41
+ ## PORTS
42
+ - stock { entrer({ articleId, quantite, montant, ref, cle, par, lot, peremption }) → { id? },
43
+ disponible(articleId) → entier, consommation(articleId, { depuis, jusqua }) → entier } (ms depuis l'époque)
44
+ portStocks(createStocks(...)) : movements.in (qty, amount, ref, by, lot, expiry), levels.of().free,
45
+ somme des sorties et des consommations de transformation de movements.list({ articleId })
46
+ - fournisseurs { parId(id) → { actif } | null, fournisseursPourMatiere(articleId) → [{ fournisseurId, code, parColis, libelle }] }
47
+ l'objet de creerFournisseurs() de @mostajs/fournisseurs 0.2.0 convient TEL QUEL
48
+ - numeroter ({ type, le, fournisseurId }) → string ; portNumerotation(createNumbering()) ; absent → numero null
49
+ - horloge () → ms | Date (défaut Date.now) · id () → string (défaut crypto.randomUUID)
50
+ - reglages objet ou () → objet : { excedent: 'refuser', fenetreJours: 30, couvertureJours: 30 } (lus à chaque appel)
51
+
52
+ ## EXEMPLES (publiés, exécutables depuis le paquet installé, sans autre module)
53
+ - exemples/01-quantite-proposee.mjs calculerQuantite : point de commande, position, sécurité en jours, minimum, refus à code
54
+ - exemples/02-cycle-commande.mjs proposer → brouillonsDepuis → envoyer → recevoir (partiel, excédent refusé puis accepté)
55
+ → solder avec motif → annuler ; ports stock, fournisseurs, numeroter écrits en quelques lignes
56
+ - exemples/03-reprise-apres-panne.mjs ENTREE_STOCK_ECHOUEE → aReprendre → reprendreEntrees, sans double entrée
57
+ - exemples/tous.mjs les lance tous (code 0 = vérifiés) : node node_modules/@mostajs/achats/exemples/tous.mjs
58
+ Chaque exemple importe '@mostajs/achats' et node:* seulement, et se vérifie lui-même (assertions).
59
+ Hors du paquet : integration/reapprovisionner.mjs (dépôt seulement), sur les vrais @mostajs/stocks, fournisseurs, numbering.
60
+
61
+ ## DÉPÔT
62
+ Contrat à prédicat (@mostajs/repository), un dépôt par entité :
63
+ create(doc) → doc · findById(id) → doc | null · find(predicat) → doc[] · update(id, patch, { version }?) → doc | null
64
+ update rend null si la version stockée diffère de `version` (en base : UPDATE … WHERE id = ? AND version = ?) ;
65
+ le patch porte la nouvelle version. Le module traduit null en CONFLIT_VERSION. depotMemoire() le tient (copies isolées).
66
+
67
+ ## ÉTATS
68
+ brouillon → envoyee → recue_partiellement → soldee ; brouillon | envoyee → annulee ; recue_partiellement → soldee (solder)
69
+ Une commande close nomme son état : COMMANDE_SOLDEE, COMMANDE_ANNULEE.
70
+
71
+ ## QUANTITÉ PROPOSÉE (entiers, plafonds)
72
+ demandePendantDelai = ⌈q × delaiJours / jours⌉ ; stockSecurite = donné ou ⌈q × stockSecuriteJours / jours⌉
73
+ pointDeCommande = demandePendantDelai + stockSecurite ; position = disponible + enCommande ; declenche = position ≤ point
74
+ niveauCible = point + ⌈q × couvertureJours / jours⌉ ; quantite = max(⌈max(cible − position, 1) / multiple⌉, ⌈minimum / multiple⌉) × multiple
75
+
76
+ ## PERMISSIONS (contribuées, jamais attribuées à un rôle ; l'application les vérifie avant l'appel)
77
+ achats:lire · achats:proposer · achats:commander · achats:envoyer · achats:recevoir · achats:cloturer
78
+
79
+ ## CODES
80
+ CONFIG_INVALIDE PORT_ABSENT DONNEES_INVALIDES QUANTITE_INVALIDE MONTANT_INVALIDE LIGNES_VIDES LIGNE_EN_DOUBLE LIGNE_INCONNUE
81
+ FOURNISSEUR_INCONNU FOURNISSEUR_INACTIF COMMANDE_INCONNUE COMMANDE_NON_MODIFIABLE COMMANDE_NON_ENVOYEE COMMANDE_SOLDEE
82
+ COMMANDE_ANNULEE TRANSITION_INTERDITE ANNULATION_IMPOSSIBLE MOTIF_REQUIS RECEPTION_VIDE RECEPTION_EXCEDENTAIRE
83
+ RECEPTION_INCONNUE ENTREE_STOCK_ECHOUEE CONFLIT_VERSION
84
+
85
+ ## PIÈGES
86
+ - montants et quantités : ENTIERS sûrs (unité monétaire entière, unité de stock entière) ; 12.5 → MONTANT_INVALIDE
87
+ - quantite d'une ligne = en unités de COMMANDE (colis) ; en stock entre quantite × parColis ; montant = quantite × prixUnitaire
88
+ - le numéro est tiré à l'ENVOI : un brouillon ne consomme pas de numéro ; un CONFLIT_VERSION à l'envoi en perd un
89
+ - excédent refusé par défaut, SANS rien écrire (details.lignes : reste et reçu) ; excedent: 'accepter' l'entre au prix de la commande
90
+ - un brouillon n'est PAS « en commande » (enCommande) ; proposer rend enBrouillon pour éviter la double commande
91
+ - après ENTREE_STOCK_ECHOUEE la commande porte déjà la livraison : appeler reprendreEntrees(details.receptionId), jamais recevoir
92
+ - port entrer : `cle` = '<réception>:<ligne>' permet à l'application d'ignorer une entrée rejouée
93
+ - @mostajs/fournisseurs 0.2.0 n'a pas de délai de livraison et son minimumCommande n'a pas d'unité : délai et minimum
94
+ viennent des Paramètres de l'application
95
+ - le module ne vérifie AUCUNE permission : PERMISSION_PAR_OPERATION dit laquelle vérifier ; jamais de rôle dans le code
96
+
97
+ ## NE FAIT PAS
98
+ - mouvements, niveaux, seuils, valorisation → @mostajs/stocks
99
+ - référentiel des fournisseurs, références code ↔ matière → @mostajs/fournisseurs
100
+ - facture d'achat, rapprochement facture, écritures → @mostajs/compta (lecture de facture : stocks.approvisionnement)
101
+ - numérotation → @mostajs/numbering
102
+ - recherche d'offres, comparaison de prix → @mostajs/sourcing
103
+ - bon de commande en PDF, envoi par courriel → @mostajs/file-export, @mostajs/mailer
104
+ - attribution des permissions à des rôles → @mostajs/rbac (l'administrateur coche la matrice)
105
+ - écrans → l'application
package/package.json CHANGED
@@ -1,6 +1,84 @@
1
1
  {
2
2
  "name": "@mostajs/achats",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Commandes fournisseurs : cycle de vie (brouillon, envoyée, reçue en partie, soldée, annulée), quantité proposée au point de commande avec stock de sécurité, réception partielle ou excédentaire qui entre en stock par un port injecté ; montants entiers, horloge et dépôts injectés, erreurs à codes, permissions contribuées.",
5
+ "license": "AGPL-3.0-or-later",
6
+ "author": "Dr Hamid MADANI <drmdh@msn.com>",
7
+ "type": "module",
8
+ "main": "src/index.mjs",
9
+ "exports": {
10
+ ".": "./src/index.mjs",
11
+ "./register": "./src/register.mjs",
12
+ "./package.json": "./package.json"
13
+ },
14
+ "files": [
15
+ "src",
16
+ "exemples",
17
+ "llms.txt",
18
+ "README.md",
19
+ "CHANGELOG.md",
20
+ "LICENSE"
21
+ ],
22
+ "engines": {
23
+ "node": ">=20"
24
+ },
25
+ "scripts": {
26
+ "test": "bash test-scripts/run-tests.sh",
27
+ "exemples": "node exemples/tous.mjs",
28
+ "exemple:integration": "node integration/reapprovisionner.mjs"
29
+ },
30
+ "keywords": [
31
+ "mostajs",
32
+ "achats",
33
+ "purchasing",
34
+ "purchase-order",
35
+ "commande-fournisseur",
36
+ "reapprovisionnement",
37
+ "reorder-point",
38
+ "point-de-commande",
39
+ "stock-de-securite",
40
+ "reception"
41
+ ],
42
+ "dependencies": {},
43
+ "devDependencies": {
44
+ "@mostajs/fournisseurs": "0.2.0",
45
+ "@mostajs/layer-lint": "^0.2.0",
46
+ "@mostajs/mjs-unit": "0.16.1",
47
+ "@mostajs/numbering": "0.1.1",
48
+ "@mostajs/stocks": "0.5.0"
49
+ },
50
+ "mostajs": {
51
+ "niveau": "N1",
52
+ "nature": "generique",
53
+ "reutilisabilite": "transverse",
54
+ "depend_de": [],
55
+ "question": "Que commander, à qui, et qu'en a-t-on reçu ?",
56
+ "forme": "moteur",
57
+ "entites": [
58
+ "CommandeAchat",
59
+ "ReceptionAchat"
60
+ ],
61
+ "verbes": [
62
+ "proposer",
63
+ "creer",
64
+ "envoyer",
65
+ "recevoir",
66
+ "solder",
67
+ "annuler"
68
+ ],
69
+ "interop": [
70
+ "point de commande et stock de sécurité (méthode classique de réapprovisionnement, politique (s, S))",
71
+ "montants en entiers dans l'unité monétaire (aucun flottant)",
72
+ "contrat de dépôt à prédicat { create, findById, update, find } (@mostajs/repository), avec version optimiste"
73
+ ],
74
+ "ne_fait_pas": [
75
+ "aucun mouvement ni niveau de stock → @mostajs/stocks (port stock injecté)",
76
+ "aucun référentiel de fournisseurs ni de références → @mostajs/fournisseurs (port injecté)",
77
+ "aucune facture d'achat ni écriture comptable → @mostajs/compta",
78
+ "aucune numérotation propre → @mostajs/numbering (port numeroter)",
79
+ "aucune recherche d'offres ni comparaison de prix → @mostajs/sourcing",
80
+ "aucun bon de commande en PDF ni envoi au fournisseur → @mostajs/file-export, @mostajs/mailer",
81
+ "aucune attribution de permission à un rôle → @mostajs/rbac (l'administrateur)"
82
+ ]
83
+ }
84
+ }
@@ -0,0 +1,43 @@
1
+ // @mostajs/achats — adaptateurs des ports aux API RÉELLES des modules voisins.
2
+ // @mostajs/fournisseurs 0.2.0 n'en a pas besoin : `parId` et `fournisseursPourMatiere` s'appellent tels quels.
3
+ // @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
4
+
5
+ const ms = (t) => (t instanceof Date ? t.getTime() : typeof t === 'number' ? t : new Date(t).getTime());
6
+
7
+ /**
8
+ * Port stock depuis l'objet rendu par createStocks() de @mostajs/stocks 0.5.0.
9
+ * entrer → stocks.movements.in(articleId, { qty, amount, ref, by, lot, expiry })
10
+ * disponible → stocks.levels.of(articleId).free (disponible non réservé)
11
+ * consommation → sorties (kind 'out') et consommations de transformation (lignes négatives) dans [depuis, jusqua]
12
+ */
13
+ export function portStocks(stocks) {
14
+ return {
15
+ async entrer({ articleId, quantite, montant, ref, par, lot = null, peremption = null }) {
16
+ const m = await stocks.movements.in(articleId, { qty: quantite, amount: montant, ref, by: par ?? null, lot, expiry: peremption });
17
+ return { id: m?.id ?? null };
18
+ },
19
+ async disponible(articleId) {
20
+ const n = await stocks.levels.of(articleId);
21
+ return n.free ?? n.available ?? n.qty;
22
+ },
23
+ async consommation(articleId, { depuis, jusqua }) {
24
+ const de = ms(depuis); const a = ms(jusqua);
25
+ let total = 0;
26
+ for (const m of await stocks.movements.list({ articleId })) {
27
+ const t = ms(m.at ?? m.createdAt);
28
+ if (!(t >= de && t <= a)) continue;
29
+ if (m.kind === 'out' && m.articleId === articleId) total += Number(m.qty) || 0;
30
+ else if (m.kind === 'transform') for (const l of m.lines || []) if (l.articleId === articleId && l.qty < 0) total += -l.qty;
31
+ }
32
+ return total;
33
+ },
34
+ };
35
+ }
36
+
37
+ /**
38
+ * Port de numérotation depuis @mostajs/numbering 0.1.1 : la séquence `nom` est définie par l'application
39
+ * (format pris dans ses Paramètres), par exemple numbering.define({ name: 'commande-achat', format: '[BC]-YYYY-NNNN', resetEvery: 'year' }).
40
+ */
41
+ export function portNumerotation(numbering, { nom = 'commande-achat' } = {}) {
42
+ return ({ le }) => numbering.next(nom, { date: new Date(le) });
43
+ }