@mostajs/stocks 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# @mostajs/stocks
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+
+Gestion des **stocks / inventaire** (couche logique) — articles, mouvements
+(entrées/sorties/ajustements), **niveaux** calculés, **lots & péremption**, **seuils & alertes**,
+**valorisation PMP**. **Compose** des repositories injectés (DEVRULES §10) ; DB-agnostique.
+
+```js
+import { createStocks, ArticleSchema, StockMovementSchema } from '@mostajs/stocks';
+const s = createStocks({ repositories: { articles, movements } }); // repos ORM/data-plug
+const a = await s.articles.create({ name: 'Lait', unit: 'L', minThreshold: 10 });
+await s.movements.in(a.id, { qty: 50, unitCost: 90, lot: 'L1', expiry: '2026-08-01' });
+await s.movements.out(a.id, { qty: 45, beneficiaryId: 'ben-1' });   // refuse le stock négatif
+await s.levels.of(a.id);        // { qty: 5, byLot }
+await s.alerts.lowStock();      // articles ≤ seuil
+await s.alerts.expiringSoon({ days: 30 });
+await s.valorize();             // { total, method: 'pmp' }
+```
+
+Tests & exemple (§11.1 / §12) : `npm install && npm test`. Conception : `DESIGN.md`. Proposition &
+livrables : `docs/`. Fiche LLM : `llms.txt`.

package/llms.txt

@@ -0,0 +1,38 @@
+# @mostajs/stocks — fiche LLM
+> Gestion des stocks / inventaire : articles, mouvements, niveaux, lots & péremption, seuils & alertes, valorisation PMP.
+
+- Version: 0.1.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Stack: mosta-gestion-stack
+
+## RÔLE
+Couche LOGIQUE d'inventaire, DB-agnostique (repositories injectés, §10). Suit des ARTICLES et leurs
+MOUVEMENTS (entrées/sorties/ajustements), calcule les NIVEAUX, alerte sur seuils & péremption, valorise
+en PMP. Ne réimplémente ni persistance ni numérotation.
+
+## EXPORTS
+- createStocks({ repositories, now? }) -> { articles, movements, levels, alerts, valorize }
+- ArticleSchema, StockMovementSchema  (EntitySchema @mostajs/orm)
+
+## API
+- articles: create(data), update(id,patch), get(id), list(), deactivate(id)
+- movements:
+  - in(articleId, { qty, lot?, expiry?, unitCost?, ref?, by? })       entrée (don/achat)
+  - out(articleId, { qty, ref?, beneficiaryId?, by? })                sortie (refuse stock négatif)
+  - adjust(articleId, { qty, reason?, by? })                          ajustement signé (casse/inventaire)
+  - list({ articleId? })
+- levels: of(articleId) -> { articleId, qty, byLot }, all() -> { article, qty, byLot }[]
+- alerts: lowStock() -> articles ≤ seuil, expiringSoon({ days }) -> lots proches péremption
+- valorize() -> { total, method:'pmp' }   (prix moyen pondéré des entrées)
+
+## REPOSITORIES (contrat injecté)
+- articles, movements : chacun { create, findById, update, find(predicate) }
+  (l'app registre ArticleSchema / StockMovementSchema sur son ORM/data-plug)
+
+## ROADMAP
+FEFO strict par lot (dépletion), multi-emplacements & transferts, valorisation FIFO, sortie = aide en
+nature (lien @mostajs/aid-grants) + pièce @mostajs/ged, inventaires tournants.
+
+## PIÈGES
+- `out` refuse de passer le stock négatif (contrôle de disponibilité).
+- `adjust` prend une qté SIGNÉE (négative = casse/perte).
+- valorize = PMP simple sur les entrées (FIFO = roadmap).

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mostajs/stocks",
+  "version": "0.1.0",
+  "description": "Gestion des stocks / inventaire — articles, mouvements (entrées/sorties/ajustements), niveaux, lots & péremption, seuils & alertes, valorisation PMP. DB-agnostique (repositories injectés).",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "llms.txt"
+  ],
+  "keywords": [
+    "stock",
+    "inventaire",
+    "inventory",
+    "warehouse",
+    "mostajs"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "node test-scripts/unit/stocks.test.mjs && node examples/run.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,123 @@
+// @mostajs/stocks — gestion des stocks / inventaire (couche logique). MVP.
+// Articles + mouvements (entrées/sorties/ajustements), niveaux calculés, lots & péremption,
+// seuils & alertes, valorisation PMP. COMPOSE par INJECTION (DEVRULES §10) : repositories
+// injectés (DB-agnostique) ; ne réimplémente ni la persistance ni la numérotation.
+// @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+
+/** Article de stock (EntitySchema @mostajs/orm). */
+export const ArticleSchema = {
+  name: 'Article', collection: 'stock_articles', timestamps: true,
+  fields: {
+    name: { type: 'string', required: true }, sku: { type: 'string', default: null },
+    unit: { type: 'string', default: 'u' }, category: { type: 'string', default: null },
+    minThreshold: { type: 'number', default: 0 }, perishable: { type: 'boolean', default: false },
+    active: { type: 'boolean', default: true },
+  },
+  indexes: [{ fields: { category: 'asc' } }],
+};
+/** Mouvement de stock (EntitySchema @mostajs/orm). */
+export const StockMovementSchema = {
+  name: 'StockMovement', collection: 'stock_movements', timestamps: true,
+  fields: {
+    articleId: { type: 'string', required: true }, kind: { type: 'string', required: true }, // in|out|adjust
+    qty: { type: 'number', default: 0 }, lot: { type: 'string', default: null }, expiry: { type: 'date', default: null },
+    unitCost: { type: 'number', default: 0 }, ref: { type: 'string', default: null },
+    beneficiaryId: { type: 'string', default: null }, reason: { type: 'string', default: null },
+    by: { type: 'string', default: null }, at: { type: 'date' },
+  },
+  indexes: [{ fields: { articleId: 'asc' } }, { fields: { kind: 'asc' } }],
+};
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+
+/**
+ * @param {object} opts
+ * @param {object} opts.repositories  { articles, movements } — chacun { create, findById, update, find(predicate) }
+ * @param {() => Date} [opts.now]
+ */
+export function createStocks({ repositories = {}, now = () => new Date() } = {}) {
+  const articlesRepo = repositories.articles;
+  const movementsRepo = repositories.movements;
+  if (!articlesRepo || !movementsRepo) throw new Error('createStocks: repositories.articles et .movements requis');
+
+  const articles = {
+    create: (data) => articlesRepo.create({ unit: 'u', minThreshold: 0, perishable: false, active: true, ...data }),
+    update: (id, patch) => articlesRepo.update(id, patch),
+    get: (id) => articlesRepo.findById(id),
+    list: () => articlesRepo.find((a) => a.active !== false),
+    deactivate: (id) => articlesRepo.update(id, { active: false }),
+  };
+
+  const movementsOf = (articleId) => movementsRepo.find((m) => m.articleId === articleId);
+
+  const levels = {
+    /** Niveau courant d'un article : qté, valeur (cumul des entrées), lots. */
+    async of(articleId) {
+      const ms = await movementsOf(articleId);
+      let qty = 0; const lots = {};
+      for (const m of ms) {
+        if (m.kind === 'in') { qty += num(m.qty); if (m.lot) lots[m.lot] = (lots[m.lot] || 0) + num(m.qty); }
+        else if (m.kind === 'out') qty -= num(m.qty);
+        else if (m.kind === 'adjust') qty += num(m.qty); // signé
+      }
+      return { articleId, qty, byLot: lots };
+    },
+    async all() {
+      const arts = await articles.list();
+      return Promise.all(arts.map(async (a) => ({ article: a, ...(await levels.of(a.id)) })));
+    },
+  };
+
+  const movements = {
+    /** Entrée (don/achat). */
+    async in(articleId, { qty, lot = null, expiry = null, unitCost = 0, ref = null, by = null } = {}) {
+      if (!(num(qty) > 0)) throw new Error('stocks.in: quantité invalide');
+      return movementsRepo.create({ articleId, kind: 'in', qty: num(qty), lot, expiry, unitCost: num(unitCost), ref, beneficiaryId: null, reason: null, by, at: now() });
+    },
+    /** Sortie (distribution) — refuse de passer le stock négatif. */
+    async out(articleId, { qty, ref = null, beneficiaryId = null, by = null } = {}) {
+      if (!(num(qty) > 0)) throw new Error('stocks.out: quantité invalide');
+      const lvl = await levels.of(articleId);
+      if (num(qty) > lvl.qty) throw new Error(`stocks.out: stock insuffisant (disponible ${lvl.qty}, demandé ${num(qty)})`);
+      return movementsRepo.create({ articleId, kind: 'out', qty: num(qty), lot: null, expiry: null, unitCost: 0, ref, beneficiaryId, reason: null, by, at: now() });
+    },
+    /** Ajustement d'inventaire (qté signée : casse, péremption, recomptage). */
+    async adjust(articleId, { qty, reason = 'inventaire', by = null } = {}) {
+      return movementsRepo.create({ articleId, kind: 'adjust', qty: num(qty), lot: null, expiry: null, unitCost: 0, ref: null, beneficiaryId: null, reason, by, at: now() });
+    },
+    list: ({ articleId } = {}) => (articleId ? movementsOf(articleId) : movementsRepo.find(() => true)),
+  };
+
+  const alerts = {
+    /** Articles dont le stock est ≤ seuil minimal. */
+    async lowStock() {
+      const all = await levels.all();
+      return all.filter((x) => x.qty <= num(x.article.minThreshold)).map((x) => ({ article: x.article, qty: x.qty, minThreshold: num(x.article.minThreshold) }));
+    },
+    /** Lots dont la péremption tombe dans `days` jours (entrées avec date). */
+    async expiringSoon({ days = 30 } = {}) {
+      const ms = (await movementsRepo.find((m) => m.kind === 'in' && m.expiry));
+      const limit = new Date(now().getTime() + days * 86400000).getTime();
+      return ms.filter((m) => new Date(m.expiry).getTime() <= limit)
+        .map((m) => ({ articleId: m.articleId, lot: m.lot, expiry: m.expiry, qty: num(m.qty) }));
+    },
+  };
+
+  /** Valorisation du stock (PMP — prix moyen pondéré des entrées). */
+  async function valorize() {
+    const all = await levels.all();
+    let total = 0;
+    for (const x of all) {
+      const ins = (await movementsOf(x.article.id)).filter((m) => m.kind === 'in');
+      const inQty = ins.reduce((s, m) => s + num(m.qty), 0);
+      const inVal = ins.reduce((s, m) => s + num(m.qty) * num(m.unitCost), 0);
+      const pmp = inQty ? inVal / inQty : 0;
+      total += x.qty * pmp;
+    }
+    return { total: Math.round(total * 100) / 100, method: 'pmp' };
+  }
+
+  return { now, articles, movements, levels, alerts, valorize };
+}
+
+export default createStocks;