@mostajs/attendance 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @mostajs/attendance
+## [0.1.0] — 2026-06-18
+### Added
+- Pointage manuel/QR/visage, absences, alertes (notifications), stats (taux de présence). Compose @mostajs/users + @mostajs/face.
+- 5 tests + exemple §12 (classe : visage+QR+manuel, alerte parent).

package/README.md

@@ -0,0 +1,10 @@
+# @mostajs/attendance
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (5 tests verts)
+> Présences : manuel/QR/visage, absences, alertes parents, stats. Détenteur = @mostajs/users ; compose @mostajs/face + notifications.
+```js
+import { createAttendance, createMemoryRepositories } from '@mostajs/attendance';
+const at = createAttendance({ repositories: createMemoryRepositories(), users, notifications });
+await at.markByQr(sessionId, badgeCode);     // ou markByFace(sessionId, descriptor) / mark(...)
+await at.alertAbsence(learnerId, { contact: 'parent@x' });
+```
+Lancer : `node test-scripts/unit/attendance.test.mjs && node examples/classe/run.mjs`

package/docs/00-PROPOSITION-PLAN-ATTENDANCE-18062026.md

@@ -0,0 +1,12 @@
+# @mostajs/attendance — DEVRULES de bout en bout (§4 + #3 + #4 condensés)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : cas C (P1, ATC F4 + accès)
+**Principe** : EXTRACTION du patron présence (ATC + contrôle d'accès SecuAccessPro). Détenteur = @mostajs/users.
+## §4 / §3
+Pointage **manuel/QR/carte/visage** + **absences** + **alertes parents** + **stats**. DB-agnostique.
+**Compose** : @mostajs/users (identifier par qrCode/matchFace→@mostajs/face), notifications (alertes), scan/pwa-scan (capture).
+**Frontière** : la séance/cours = @mostajs/training (sessionId opaque) ; attendance ne gère que la présence.
+**API** : `createAttendance({repositories,users?,notifications?})` → `mark(sessionId,learnerId,{status,method,by})`,
+`markByQr(sessionId,code)`, `markByFace(sessionId,descriptor)`, `listBySession/listByLearner/absences`, `stats(sessionId)`, `alertAbsence(learnerId,{contact})`.
+**Jalons** : 0.1 mark+stats · 0.2 markByQr/markByFace(users/face)+absences/alertes · 0.3 scan/pwa-scan UI · 1.0 14 livrables.
+## §4 (tests)
+mark idempotent, markByQr (users), markByFace (face réel), stats(taux), absences+alerte notifications. (5 verts)

package/examples/classe/run.mjs

@@ -0,0 +1,20 @@
+// Exemple §12 — présences d'une classe (manuel + QR + visage) + alerte parent. node examples/classe/run.mjs
+import assert from 'node:assert/strict';
+import { createAttendance, createMemoryRepositories } from '../../src/index.js';
+import { createUsers, createMemoryRepositories as userRepos } from '../../../mosta-users-stack/mosta-users/src/index.js';
+import { findMatch } from '../../../mosta-face/dist/lib/face-matcher.js';
+const desc=(s)=>Array.from({length:128},(_,i)=>Math.sin(s*(i+1))*0.5);
+const users=createUsers({ repositories:userRepos(), face:{ findMatch }, qr:{ generate:(id)=>'BADGE:'+id } });
+const e1=await users.create({firstName:'Inès'}); await users.enrollFace(e1.id, desc(1));
+const e2=await users.create({firstName:'Karim'});
+const e3=await users.create({firstName:'Sami'});
+const at=createAttendance({ repositories:createMemoryRepositories(), users, notifications:{ notify:(e)=>console.log('   ↪ alerte parent:',e.type,e.contact) } });
+const SES='ENG-A1-mardi';
+await at.markByFace(SES, desc(1).map(x=>x+0.002));   // Inès par visage
+await at.markByQr(SES, e2.qrCode);                    // Karim par badge
+await at.mark(SES, e3.id, { status:'absent' });       // Sami absent (pointage manuel)
+const st=await at.stats(SES);
+assert.equal(st.present,2); assert.equal(st.absent,1);
+await at.alertAbsence(e3.id, { contact:'parent.sami@ex.dz' });
+console.log('✅ attendance — classe %s : présents %d/%d (taux %s) · visage+QR+manuel',
+  SES, st.present, st.total, st.presenceRate.toFixed(2));

package/llms.txt

@@ -0,0 +1,13 @@
+# @mostajs/attendance — fiche LLM
+RÔLE
+  Présences génériques : pointage manuel/QR/carte/visage, absences, alertes parents, stats. DB-agnostique.
+  Détenteur = @mostajs/users (résolution qrCode/matchFace→@mostajs/face). Compose notifications/scan. Délègue la séance à @mostajs/training.
+EXPORTS
+  createAttendance({ repositories, users?, notifications?, now? }) -> api ; createMemoryRepositories(); AttendanceRecordSchema
+API
+  mark(sessionId,learnerId,{status:'present'|'absent'|'late'|'excused',method:'manual'|'qr'|'card'|'face',by})  (1 enreg./séance+apprenant)
+  markByQr(sessionId,code)  markByFace(sessionId,descriptor)  listBySession/listByLearner/absences
+  stats(sessionId) -> {total,present,late,absent,excused,presenceRate}  alertAbsence(learnerId,{contact})
+PIÈGES
+  - markByQr exige users (qrCode) ; markByFace exige users.matchFace (face injecté). sessionId opaque (→ training).
+  - mark = upsert par (séance, apprenant). Alerte parents = compose notifications.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mostajs/attendance",
+  "version": "0.1.0",
+  "description": "Présences génériques : pointage manuel/QR/carte/visage, absences, alertes. Détenteur = @mostajs/users ; compose face/scan/notifications. DB-agnostique.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schemas": "./src/schemas.js"
+  },
+  "keywords": [
+    "mostajs",
+    "attendance",
+    "presence",
+    "qr",
+    "face",
+    "absences"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/attendance.test.mjs",
+    "example": "node examples/classe/run.mjs"
+  }
+}

package/src/attendance.js

@@ -0,0 +1,50 @@
+// @mostajs/attendance — présences. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Détenteur = @mostajs/users (identification par QR/visage). Compose users(matchFace)/notifications. Délègue séance à training.
+
+export function createAttendance({ repositories, users, notifications, now = () => new Date() } = {}) {
+  if (!repositories?.records) throw new Error('createAttendance: repositories.records requis');
+  const { records } = repositories;
+  const findOne = async (sessionId, learnerId) => (await records.find((r) => r.sessionId === sessionId && r.learnerId === learnerId))[0];
+
+  async function mark(sessionId, learnerId, { status = 'present', method = 'manual', by } = {}) {
+    const ex = await findOne(sessionId, learnerId);
+    return ex ? records.update(ex.id, { status, method, at: now(), markedBy: by }) // un enregistrement par (séance, apprenant)
+      : records.create({ sessionId, learnerId, status, method, at: now(), markedBy: by });
+  }
+  const listByLearner = (learnerId) => records.find((r) => r.learnerId === learnerId);
+  const absences = (learnerId) => records.find((r) => r.learnerId === learnerId && r.status === 'absent');
+
+  const api = {
+    mark,
+    /** Pointage par badge QR (résout l'apprenant via @mostajs/users qrCode). */
+    async markByQr(sessionId, code, opts = {}) {
+      if (!users?.repositories?.users) throw new Error('users requis (markByQr)');
+      const u = (await users.repositories.users.find((x) => x.qrCode === code))[0];
+      if (!u) throw new Error('badge inconnu');
+      return mark(sessionId, u.id, { method: 'qr', status: 'present', ...opts });
+    },
+    /** Pointage par visage (résout via @mostajs/users matchFace → @mostajs/face). */
+    async markByFace(sessionId, descriptor, opts = {}) {
+      if (!users?.matchFace) throw new Error('users.matchFace requis (markByFace)');
+      const m = await users.matchFace(descriptor);
+      if (!m) throw new Error('visage inconnu');
+      return mark(sessionId, m.match.id, { method: 'face', status: 'present', ...opts });
+    },
+    listBySession: (sessionId) => records.find((r) => r.sessionId === sessionId),
+    listByLearner, absences,
+    async stats(sessionId) {
+      const rs = await records.find((r) => r.sessionId === sessionId);
+      const by = (s) => rs.filter((r) => r.status === s).length;
+      const present = by('present') + by('late');
+      return { total: rs.length, present: by('present'), late: by('late'), absent: by('absent'), excused: by('excused'), presenceRate: rs.length ? present / rs.length : 0 };
+    },
+    /** Alerte d'absence (compose @mostajs/notifications → parents). */
+    async alertAbsence(learnerId, { contact } = {}) {
+      const abs = await absences(learnerId);
+      if (abs.length) notifications?.notify?.({ type: 'attendance.absence', learnerId, contact, count: abs.length });
+      return abs.length;
+    },
+    repositories,
+  };
+  return api;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/attendance — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { createAttendance } from './attendance.js';
+export { createMemoryRepositories } from './memory-repo.js';
+export { AttendanceRecordSchema } from './schemas.js';

package/src/memory-repo.js

@@ -0,0 +1,7 @@
+// @mostajs/attendance — repos mémoire. Author: Dr Hamid MADANI <drmdh@msn.com>
+function coll() { const m = new Map(); return {
+  async create(d) { const id = d.id || globalThis.crypto.randomUUID(); const now = new Date(); const r = { id, createdAt: now, updatedAt: now, ...d }; m.set(id, r); return { ...r }; },
+  async findById(id) { const r = m.get(id); return r ? { ...r } : null; },
+  async update(id, p) { const r = m.get(id); if (!r) return null; const x = { ...r, ...p, updatedAt: new Date() }; m.set(id, x); return { ...x }; },
+  async find(f = () => true) { return [...m.values()].filter(f).map((r) => ({ ...r })); } }; }
+export function createMemoryRepositories() { return { records: coll() }; }

package/src/schemas.js

@@ -0,0 +1,13 @@
+// @mostajs/attendance — schéma (EntitySchema @mostajs/orm). Author: Dr Hamid MADANI <drmdh@msn.com>
+export const AttendanceRecordSchema = {
+  name: 'AttendanceRecord', collection: 'attendance_records', timestamps: true,
+  fields: {
+    sessionId: { type: 'string', required: true },     // séance/groupe (ex. @mostajs/training Session)
+    learnerId: { type: 'string', required: true },     // détenteur (@mostajs/users)
+    status: { type: 'string', enum: ['present', 'absent', 'late', 'excused'], default: 'present' },
+    method: { type: 'string', enum: ['manual', 'qr', 'card', 'face'], default: 'manual' },
+    at: { type: 'date', default: 'now' },
+    markedBy: { type: 'string', default: null },
+  },
+  indexes: [{ fields: { sessionId: 'asc' } }, { fields: { learnerId: 'asc' } }],
+};

package/test-scripts/unit/attendance.test.mjs

@@ -0,0 +1,41 @@
+// @mostajs/attendance — tests (DEVRULES §5). node test-scripts/unit/attendance.test.mjs
+import assert from 'node:assert/strict';
+import { createAttendance, createMemoryRepositories } from '../../src/index.js';
+import { createUsers, createMemoryRepositories as userRepos } from '../../../mosta-users-stack/mosta-users/src/index.js';
+import { findMatch } from '../../../mosta-face/dist/lib/face-matcher.js';
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+const desc=(s)=>Array.from({length:128},(_,i)=>Math.sin(s*(i+1))*0.5);
+
+await test('mark idempotent par (séance, apprenant)', async()=>{
+  const at=createAttendance({ repositories:createMemoryRepositories() });
+  await at.mark('s1','l1',{status:'absent'}); await at.mark('s1','l1',{status:'present',method:'manual'});
+  const rs=await at.listBySession('s1'); assert.equal(rs.length,1); assert.equal(rs[0].status,'present');
+});
+await test('markByQr résout via users (qrCode)', async()=>{
+  const users=createUsers({ repositories:userRepos(), qr:{ generate:(id)=>'BADGE:'+id } });
+  const u=await users.create({firstName:'A'});
+  const at=createAttendance({ repositories:createMemoryRepositories(), users });
+  const r=await at.markByQr('s1', u.qrCode); assert.equal(r.learnerId,u.id); assert.equal(r.method,'qr');
+  await assert.rejects(()=>at.markByQr('s1','BADGE:x'), /badge inconnu/);
+});
+await test('markByFace résout via users.matchFace (@mostajs/face)', async()=>{
+  const users=createUsers({ repositories:userRepos(), face:{ findMatch } });
+  const u=await users.create({firstName:'A'}); await users.enrollFace(u.id, desc(1));
+  const at=createAttendance({ repositories:createMemoryRepositories(), users });
+  const r=await at.markByFace('s1', desc(1).map(x=>x+0.001)); assert.equal(r.learnerId,u.id); assert.equal(r.method,'face');
+  await assert.rejects(()=>at.markByFace('s1', desc(99)), /visage inconnu/);
+});
+await test('stats : taux de présence', async()=>{
+  const at=createAttendance({ repositories:createMemoryRepositories() });
+  await at.mark('s1','a',{status:'present'}); await at.mark('s1','b',{status:'late'}); await at.mark('s1','c',{status:'absent'});
+  const st=await at.stats('s1'); assert.equal(st.total,3); assert.equal(st.absent,1);
+  assert.equal(st.presenceRate.toFixed(3),(2/3).toFixed(3));
+});
+await test('absences + alerte parents (notifications)', async()=>{
+  const ev=[]; const at=createAttendance({ repositories:createMemoryRepositories(), notifications:{ notify:(e)=>ev.push(e) } });
+  await at.mark('s1','l1',{status:'absent'}); await at.mark('s2','l1',{status:'absent'});
+  assert.equal((await at.absences('l1')).length,2);
+  assert.equal(await at.alertAbsence('l1',{contact:'parent@x'}),2);
+  assert.equal(ev[0].type,'attendance.absence'); assert.equal(ev[0].count,2);
+});
+console.log(`\n✅ @mostajs/attendance — ${pass} tests OK`);