@mostajs/queue-bridge 0.2.0

package/README.md

@@ -0,0 +1,25 @@
+# @mostajs/queue-bridge
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+
+Pont **générique** de **file d'attente / RDV** — accueil → file → appel, avec **identification**
+par **badge QR** ou **reconnaissance faciale**. Orchestration pure (DEVRULES §10) : injecte un
+**moteur de file** (`ticketing`, ex. `@mostajs/queue` de TicketFlow) et un **port d'identité**
+(`identity`). Entité propre : **Visit**. DB-agnostique.
+
+```js
+import { createQueueBridge, VisitSchema } from '@mostajs/queue-bridge';
+const q = createQueueBridge({
+  repositories: { visits },                                   // ORM/data-plug
+  identity: { resolve: (tok) => verifyBadge(tok) },           // badge QR / face → { personId }
+  // ticketing: { issue: (svc) => queue.issue(svc) },         // pont TicketFlow (optionnel)
+});
+const who = await q.identify(badgeToken);
+const v   = await q.checkIn({ service: 'medecin', personId: who.personId });  // ticket + file
+await q.position(v.id);                                       // rang dans la file
+const next = await q.callNext('medecin', { counter: 'box-1' });
+await q.complete(next.id);
+```
+
+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,39 @@
+# @mostajs/queue-bridge — fiche LLM
+> Pont générique de file d'attente / RDV : accueil → file → appel, identification badge QR / reconnaissance faciale.
+
+- Version: 0.1.0 (MVP) · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Conception: DESIGN.md
+
+## RÔLE
+Orchestration PURE (DEVRULES §10) d'une file d'attente avec RDV. Entité propre : **Visit**
+(personne ↔ ticket ↔ RDV). Il INJECTE (ne réimplémente pas) : le **moteur de file** (`ticketing`,
+ex. @mostajs/queue de TicketFlow) et l'**identité** (`identity` : badge QR via qrpanel/auth-magic-qr,
+ou reconnaissance faciale via @mostajs/face). DB-agnostique (repositories injectés).
+
+## EXPORTS
+- createQueueBridge({ repositories, ticketing?, identity?, now? }) -> API
+- VisitSchema  (EntitySchema @mostajs/orm)
+
+## API
+- checkIn({ personId?, service, appointmentId?, label?, by? }) -> Visit   (accueil → file)
+- identify(token) -> { personId, … } | null     (badge QR ou face → personne, via port identity)
+- listWaiting(service?) -> Visit[]               (FIFO par heure d'arrivée)
+- callNext(service, { counter?, by? }) -> Visit | null
+- start(visitId) / complete(visitId) / cancel(visitId) -> Visit
+- status(visitId) -> Visit ; position(visitId) -> number (1-based, 0 si non en attente)
+
+## PORTS injectés
+- repositories.visits : { create, findById, update, find(predicate) }   [requis]
+- ticketing: { issue(service) -> ticket }   [optionnel ; def: compteur interne par service]
+- identity:  { resolve(token) -> { personId } }   [optionnel ; badge QR / reconnaissance faciale]
+
+## STATUTS Visit
+waiting → called → in_progress → done   (ou cancelled)
+
+## COMPOSITION (cible)
+- Salsabil : services = manager/médecin/gestionnaire/agent social/comptable ; identity = badge QR
+  (@mostajs/qrpanel scan) + face (@mostajs/face) ; pont TicketFlow via adaptateur `ticketing`.
+
+## ROADMAP (cf. DESIGN.md)
+RDV (@mostajs/booking), reconnaissance faciale (@mostajs/face 128-D), pont TicketFlow temps réel
+(Socket.io + waiting-room), multi-guichets.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mostajs/queue-bridge",
+  "version": "0.2.0",
+  "description": "Pont générique de file d'attente / RDV — orchestration Visit (accueil → file → appel), composant un moteur de file (ticketing) et l'identification (badge QR / reconnaissance faciale). DB-agnostique.",
+  "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": [
+    "queue",
+    "file-attente",
+    "ticketing",
+    "rdv",
+    "appointment",
+    "mostajs"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "node test-scripts/unit/queue-bridge.test.mjs && node examples/run.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,100 @@
+// @mostajs/queue-bridge — pont générique de file d'attente / RDV (couche logique). MVP.
+// Orchestration PURE (DEVRULES §10) : ne réimplémente pas le moteur de file — il l'injecte
+// (`ticketing`, ex. @mostajs/queue de TicketFlow) — ni l'identité (`identity`, badge QR / face).
+// Entité propre : Visit (personne ↔ ticket ↔ RDV). DB-agnostique (repositories injectés).
+// @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+
+/** Visite = passage d'une personne à l'accueil pour un service (EntitySchema @mostajs/orm). */
+export const VisitSchema = {
+  name: 'Visit', collection: 'queue_visits', timestamps: true,
+  fields: {
+    personId: { type: 'string', default: null }, service: { type: 'string', required: true },
+    ticket: { type: 'number', default: 0 }, status: { type: 'string', default: 'waiting' }, // waiting|called|in_progress|done|cancelled|no_show
+    appointmentId: { type: 'string', default: null }, label: { type: 'string', default: null },
+    reason: { type: 'string', default: null }, priority: { type: 'number', default: 0 }, // 0 normal, >0 prioritaire
+    recalls: { type: 'number', default: 0 }, fromVisitId: { type: 'string', default: null }, // parcours (re-orientation)
+    counter: { type: 'string', default: null }, by: { type: 'string', default: null },
+    checkedInAt: { type: 'date' }, calledAt: { type: 'date', default: null }, doneAt: { type: 'date', default: null },
+  },
+  indexes: [{ fields: { service: 'asc' } }, { fields: { status: 'asc' } }],
+};
+
+/**
+ * @param {object} opts
+ * @param {object} opts.repositories  { visits } — { create, findById, update, find(predicate) }
+ * @param {object} [opts.ticketing]   port moteur de file : { issue(service) -> ticket } (def: compteur interne)
+ * @param {object} [opts.identity]    port d'identification : { resolve(token) -> { personId, ... } } (badge QR / face)
+ * @param {() => Date} [opts.now]
+ */
+export function createQueueBridge({ repositories = {}, ticketing = null, identity = null, now = () => new Date() } = {}) {
+  const visits = repositories.visits;
+  if (!visits) throw new Error('createQueueBridge: repositories.visits requis');
+
+  async function nextTicket(service) {
+    if (ticketing?.issue) return ticketing.issue(service);          // pont externe (TicketFlow / @mostajs/queue)
+    const same = await visits.find((v) => v.service === service);   // repli : compteur interne par service
+    return same.length + 1;
+  }
+
+  /** Enregistre une visite (accueil) → mise en file d'attente. */
+  async function checkIn({ personId = null, service, appointmentId = null, label = null, reason = null, priority = 0, fromVisitId = null, by = null } = {}) {
+    if (!service) throw new Error('queue-bridge: service requis');
+    const ticket = await nextTicket(service);
+    return visits.create({ personId, service, ticket, status: 'waiting', appointmentId, label, reason, priority: Number(priority) || 0, recalls: 0, fromVisitId, counter: null, by, checkedInAt: now(), calledAt: null, doneAt: null });
+  }
+
+  /** Identifie une personne par badge QR ou reconnaissance faciale (port `identity`). */
+  async function identify(token) {
+    if (!identity?.resolve) return null;
+    return (await identity.resolve(token)) || null;
+  }
+
+  /** File d'attente d'un service (ou globale) : priorité décroissante puis heure d'arrivée (FIFO). */
+  async function listWaiting(service) {
+    const v = await visits.find((x) => x.status === 'waiting' && (!service || x.service === service));
+    return v.sort((a, b) => (Number(b.priority) || 0) - (Number(a.priority) || 0)
+      || new Date(a.checkedInAt).getTime() - new Date(b.checkedInAt).getTime());
+  }
+
+  /** Appelle la prochaine visite en attente d'un service. */
+  async function callNext(service, { counter = null, by = null } = {}) {
+    const [next] = await listWaiting(service);
+    if (!next) return null;
+    return visits.update(next.id, { status: 'called', calledAt: now(), counter, by });
+  }
+
+  const start = (visitId) => visits.update(visitId, { status: 'in_progress' });
+  const complete = (visitId) => visits.update(visitId, { status: 'done', doneAt: now() });
+  const cancel = (visitId) => visits.update(visitId, { status: 'cancelled' });
+  const status = (visitId) => visits.findById(visitId);
+
+  /** Rappelle une visite déjà appelée (ré-annonce). */
+  async function recall(visitId) {
+    const v = await visits.findById(visitId);
+    return visits.update(visitId, { status: 'called', calledAt: now(), recalls: (Number(v?.recalls) || 0) + 1 });
+  }
+  /** Marque une visite « absent » (appelée mais non présentée). */
+  const noShow = (visitId) => visits.update(visitId, { status: 'no_show' });
+
+  /** Ré-oriente vers un autre service (parcours multi-guichets) : clôt la visite courante
+   *  et en crée une nouvelle (nouveau ticket) dans la file cible, en conservant la personne/le RDV. */
+  async function transfer(visitId, { service, reason = null, priority, by = null } = {}) {
+    if (!service) throw new Error('queue-bridge.transfer: service cible requis');
+    const v = await visits.findById(visitId);
+    if (!v) throw new Error('queue-bridge.transfer: visite introuvable');
+    await visits.update(visitId, { status: 'done', doneAt: now() });
+    return checkIn({ personId: v.personId, service, appointmentId: v.appointmentId, label: v.label, reason, priority: priority != null ? priority : v.priority, fromVisitId: visitId, by });
+  }
+
+  /** Position (1-based) d'une visite dans sa file ; 0 si non en attente. */
+  async function position(visitId) {
+    const v = await visits.findById(visitId);
+    if (!v || v.status !== 'waiting') return 0;
+    const w = await listWaiting(v.service);
+    return w.findIndex((x) => x.id === visitId) + 1;
+  }
+
+  return { now, checkIn, identify, listWaiting, callNext, start, complete, cancel, recall, noShow, transfer, status, position };
+}
+
+export default createQueueBridge;