@mostajs/staff 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @mostajs/staff
+## [0.1.0] — 2026-06-18
+### Added
+- Profil intervenant (lié users) + diplômes (storage) + contrats + heures + vacations (heures×tarif, payout via payment). Disponibilités.
+- Généralisation de faculty. 7 tests + exemple §12 (enseignant ATC + expert incubateur).

package/README.md

@@ -0,0 +1,11 @@
+# @mostajs/staff
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (7 tests verts)
+> Intervenants (enseignants/experts/enquêteurs) : profil lié @mostajs/users, CV/diplômes, contrats, disponibilités, heures, vacations.
+```js
+import { createStaff, createMemoryRepositories } from '@mostajs/staff';
+const s = createStaff({ repositories: createMemoryRepositories(), users, payment });
+const t = await s.staff.create({ userId, type:'teacher', hourlyRate:1500 });
+await s.work.log(t.id, { hours: 4, sessionRef:'ENG-A1' });
+const due = await s.pay.vacationDue(t.id);   // { hours, rate, amount }
+```
+Lancer : `node test-scripts/unit/staff.test.mjs && node examples/intervenants/run.mjs`

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

@@ -0,0 +1,11 @@
+# @mostajs/staff — DEVRULES de bout en bout (§4 + #3 condensés)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : cas C (P1+P2+P3)
+**Principe** : GÉNÉRALISATION de `faculty` (enseignants) → intervenants (enseignant/expert/enquêteur). La PERSONNE = @mostajs/users.
+## §4 / §3
+Profil intervenant (lié `userId`) + **CV/diplômes** + **contrats** + **disponibilités** + **heures réalisées** + **vacations**.
+Autonome/DB-agnostique. **Compose** (optionnels) : users (personne), storage (diplômes), booking (dispo), payment (payout vacations).
+**Frontière** : la personne/identité = users ; la séance = training ; staff = la dimension « intervenant rémunéré ».
+**API** : `createStaff({repositories,users?,storage?,payment?})` → `staff.{create,get,byUser,list,setAvailability,getAvailability,withPerson}`,
+`diplomas.{add,list}`, `contracts.{add,list,activeAt}`, `work.{log,list,hours}`, `pay.{vacationDue,settle}`.
+**Réutilisabilité 3 P** : enseignants (P2 ATC), experts/consultants (P1 Hadhinat), enquêteurs sociaux (P3 ASSO-SEL).
+**Jalons** : 0.1 profil+diplômes+contrats+heures+vacations · 0.2 booking(dispo) · 1.0 14 livrables.

package/examples/intervenants/run.mjs

@@ -0,0 +1,22 @@
+// Exemple §12 — intervenants : enseignant (ATC) + expert (incubateur). node examples/intervenants/run.mjs
+import assert from 'node:assert/strict';
+import { createStaff, createMemoryRepositories } from '../../src/index.js';
+import { createUsers, createMemoryRepositories as userRepos } from '../../../mosta-users-stack/mosta-users/src/index.js';
+const users=createUsers({ repositories:userRepos() });
+const staff=createStaff({ repositories:createMemoryRepositories(), users, payment:{ async payout(p){ console.log('   ↪ vacation payée:',p.amount,'DA',`(${p.hours}h)`); } } });
+// P2 ATC : enseignant d'anglais
+const prof=await users.create({ firstName:'Mme', lastName:'Benali' });
+const teacher=await staff.staff.create({ userId:prof.id, type:'teacher', specialties:['anglais'], hourlyRate:1500 });
+await staff.diplomas.add(teacher.id,{ title:'Master Anglais', year:2018 });
+await staff.contracts.add(teacher.id,{ kind:'vacation', start:'2026-01-01' });
+await staff.work.log(teacher.id,{ date:'2026-06-07', hours:4, sessionRef:'ENG-A1-mardi' });
+await staff.work.log(teacher.id,{ date:'2026-06-14', hours:4, sessionRef:'ENG-A1-mardi' });
+const settle=await staff.pay.settle(teacher.id);
+assert.equal(settle.amount, 8*1500);
+const card=await staff.staff.withPerson(teacher.id);
+assert.equal(card.person.name,'Mme Benali');
+// P1 incubateur : expert accompagnement
+const exp=await users.create({ firstName:'Dr', lastName:'Karim' });
+await staff.staff.create({ userId:exp.id, type:'expert', specialties:['business-plan'], hourlyRate:3000 });
+assert.equal((await staff.staff.list({type:'expert'})).length,1);
+console.log('✅ staff — enseignant %s : %dh → %d DA · + expert incubateur', card.person.name, settle.hours, settle.amount);

package/llms.txt

@@ -0,0 +1,15 @@
+# @mostajs/staff — fiche LLM
+RÔLE
+  Intervenants (teacher/expert/trainer/investigator) : profil lié @mostajs/users (userId), CV/diplômes, contrats,
+  disponibilités, heures réalisées, vacations. Généralisation de faculty. Autonome/DB-agnostique.
+  Compose (optionnels) : users (personne/withPerson), storage (diplômes), booking (dispo), payment (payout).
+EXPORTS
+  createStaff({ repositories, users?, storage?, payment?, now? }) -> { staff, diplomas, contracts, work, pay }
+  createMemoryRepositories(); StaffSchema, DiplomaSchema, ContractSchema, WorkLogSchema
+API
+  staff.create({userId,type,specialties,hourlyRate})/get/byUser/list({type,status})/setAvailability/getAvailability/withPerson
+  diplomas.add(staffId,{title,year,bytes|fileRef,mime})/list ; contracts.add/list/activeAt(date)
+  work.log(staffId,{date,hours,sessionRef})/list/hours({from,to}) ; pay.vacationDue/settle(staffId,{from,to}) -> {hours,rate,amount}
+PIÈGES
+  - La personne reste @mostajs/users (userId opaque). vacation = heures × hourlyRate. diplômes via storage (sinon fileRef).
+  - settle compose @mostajs/payment (payout) si injecté. Disponibilités : composer @mostajs/booking en prod.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mostajs/staff",
+  "version": "0.1.0",
+  "description": "Intervenants (enseignants/experts/enquêteurs) : profil lié à @mostajs/users, CV/diplômes, contrats, disponibilités, heures réalisées, vacations. Généralisation de faculty. 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",
+    "staff",
+    "faculty",
+    "teachers",
+    "experts",
+    "contracts",
+    "vacations"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/staff.test.mjs",
+    "example": "node examples/intervenants/run.mjs"
+  }
+}

package/src/index.js

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

package/src/memory-repo.js

@@ -0,0 +1,7 @@
+// @mostajs/staff — 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 { staff: coll(), diplomas: coll(), contracts: coll(), worklogs: coll() }; }

package/src/schemas.js

@@ -0,0 +1,18 @@
+// @mostajs/staff — schémas (EntitySchema @mostajs/orm). Author: Dr Hamid MADANI <drmdh@msn.com>
+// GÉNÉRALISATION de faculty (SecuAccessPro/MostaGare). La PERSONNE = @mostajs/users (userId) ; staff = profil intervenant.
+export const StaffSchema = { name: 'Staff', collection: 'staff', timestamps: true, fields: {
+  userId: { type: 'string', required: true },                                   // → @mostajs/users
+  type: { type: 'string', enum: ['teacher', 'expert', 'trainer', 'investigator', 'other'], default: 'teacher' },
+  specialties: { type: 'array', arrayOf: 'string', default: () => [] },
+  hourlyRate: { type: 'number', default: 0 },                                   // tarif vacation
+  status: { type: 'string', enum: ['active', 'inactive'], default: 'active' } },
+  indexes: [{ fields: { userId: 'asc' } }, { fields: { type: 'asc' } }] };
+export const DiplomaSchema = { name: 'Diploma', collection: 'diplomas', timestamps: true, fields: {
+  staffId: { type: 'string', required: true }, title: { type: 'string', required: true }, year: { type: 'number' },
+  fileRef: { type: 'string', default: null } }, indexes: [{ fields: { staffId: 'asc' } }] };          // CV/diplôme via @mostajs/storage
+export const ContractSchema = { name: 'Contract', collection: 'contracts', timestamps: true, fields: {
+  staffId: { type: 'string', required: true }, kind: { type: 'string', enum: ['permanent', 'vacation', 'freelance'], default: 'vacation' },
+  start: { type: 'date' }, end: { type: 'date', default: null }, terms: { type: 'string' } }, indexes: [{ fields: { staffId: 'asc' } }] };
+export const WorkLogSchema = { name: 'WorkLog', collection: 'work_logs', timestamps: true, fields: {
+  staffId: { type: 'string', required: true }, date: { type: 'date', default: 'now' }, hours: { type: 'number', required: true },
+  sessionRef: { type: 'string', default: null }, note: { type: 'string' } }, indexes: [{ fields: { staffId: 'asc' } }] };

package/src/staff.js

@@ -0,0 +1,45 @@
+// @mostajs/staff — intervenants. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Autonome (DB-agnostique). Compose (injectés, optionnels) : users (personne), storage (CV/diplômes),
+// booking (disponibilités), payment (vacations). La personne reste @mostajs/users (userId).
+
+export function createStaff({ repositories, users, storage, payment, now = () => new Date() } = {}) {
+  if (!repositories?.staff) throw new Error('createStaff: repositories.staff requis');
+  const { staff, diplomas, contracts, worklogs } = repositories;
+  const putFile = async (bytes, mime) => { const fn = storage?.put || storage?.createFile; if (!fn) return null; const r = await fn.call(storage, bytes, { mime, mimeType: mime }); return typeof r === 'string' ? r : (r.id ?? r.key ?? r.ref); };
+  const inWindow = ({ from, to } = {}) => (r) => (!from || new Date(r.date) >= new Date(from)) && (!to || new Date(r.date) <= new Date(to));
+
+  const api = {
+    staff: {
+      create: (dto) => staff.create({ type: 'teacher', specialties: [], hourlyRate: 0, status: 'active', availability: [], ...dto }),
+      get: (id) => staff.findById(id),
+      byUser: async (userId) => (await staff.find((s) => s.userId === userId))[0] || null,
+      list: (f = {}) => staff.find((s) => Object.entries(f).every(([k, v]) => s[k] === v)),
+      setAvailability: (id, slots) => staff.update(id, { availability: slots }),     // (compose @mostajs/booking en prod)
+      getAvailability: async (id) => (await staff.findById(id))?.availability || [],
+      /** Fusionne le profil personne (@mostajs/users) si injecté. */
+      async withPerson(id) { const s = await staff.findById(id); if (!s) return null; const u = users?.get ? await users.get(s.userId) : null; return { ...s, person: u && { name: users.fullName ? users.fullName(u) : `${u.firstName || ''} ${u.lastName || ''}`.trim(), email: u.email, photo: u.photo } }; },
+    },
+    diplomas: {
+      async add(staffId, { title, year, bytes, mime, fileRef } = {}) { let ref = fileRef; if (bytes && storage) ref = await putFile(bytes, mime); return diplomas.create({ staffId, title, year, fileRef: ref }); },
+      list: (staffId) => diplomas.find((d) => d.staffId === staffId),
+    },
+    contracts: {
+      add: (staffId, dto) => contracts.create({ staffId, kind: 'vacation', ...dto }),
+      list: (staffId) => contracts.find((c) => c.staffId === staffId),
+      async activeAt(staffId, date = now()) { const t = new Date(date).getTime(); return (await contracts.find((c) => c.staffId === staffId)).filter((c) => (!c.start || new Date(c.start).getTime() <= t) && (!c.end || new Date(c.end).getTime() >= t)); },
+    },
+    work: {
+      log: (staffId, { date, hours, sessionRef, note } = {}) => worklogs.create({ staffId, date: date || now(), hours, sessionRef, note }),
+      list: (staffId, window) => worklogs.find((w) => w.staffId === staffId).then((a) => a.filter(inWindow(window))),
+      async hours(staffId, window) { return (await worklogs.find((w) => w.staffId === staffId)).filter(inWindow(window)).reduce((s, w) => s + (Number(w.hours) || 0), 0); },
+    },
+    pay: {
+      /** Vacation due = heures réalisées × tarif horaire. */
+      async vacationDue(staffId, window) { const s = await staff.findById(staffId); const h = await api.work.hours(staffId, window); return { hours: h, rate: s?.hourlyRate || 0, amount: h * (s?.hourlyRate || 0) }; },
+      /** Règlement (compose @mostajs/payment si injecté). */
+      async settle(staffId, window) { const due = await api.pay.vacationDue(staffId, window); if (payment?.payout) await payment.payout({ staffId, ...due }); return due; },
+    },
+    repositories,
+  };
+  return api;
+}

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

@@ -0,0 +1,48 @@
+// @mostajs/staff — tests (DEVRULES §5). node test-scripts/unit/staff.test.mjs
+import assert from 'node:assert/strict';
+import { createStaff, createMemoryRepositories } from '../../src/index.js';
+import { createUsers, createMemoryRepositories as userRepos } from '../../../mosta-users-stack/mosta-users/src/index.js';
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+const mk=(o={})=>createStaff({ repositories:createMemoryRepositories(), ...o });
+
+await test('create + byUser + list par type', async()=>{
+  const s=mk(); await s.staff.create({userId:'u1',type:'teacher',hourlyRate:1000});
+  await s.staff.create({userId:'u2',type:'expert'});
+  assert.equal((await s.staff.byUser('u1')).type,'teacher');
+  assert.equal((await s.staff.list({type:'teacher'})).length,1);
+});
+await test('diplômes (storage composé)', async()=>{
+  const store=[]; const s=mk({ storage:{ async put(b){const id='f'+store.length;store.push(b);return {id};} } });
+  const st=await s.staff.create({userId:'u1'});
+  const d=await s.diplomas.add(st.id,{title:'Master',year:2020,bytes:'pdf-bytes',mime:'application/pdf'});
+  assert.equal(d.fileRef,'f0'); assert.equal((await s.diplomas.list(st.id)).length,1);
+});
+await test('contrats + actif à une date', async()=>{
+  const s=mk(); const st=await s.staff.create({userId:'u1'});
+  await s.contracts.add(st.id,{kind:'vacation',start:'2026-01-01',end:'2026-12-31'});
+  assert.equal((await s.contracts.activeAt(st.id,'2026-06-01')).length,1);
+  assert.equal((await s.contracts.activeAt(st.id,'2025-01-01')).length,0);
+});
+await test('heures réalisées + vacation due (heures × tarif)', async()=>{
+  const s=mk(); const st=await s.staff.create({userId:'u1',hourlyRate:1200});
+  await s.work.log(st.id,{date:'2026-06-01',hours:3}); await s.work.log(st.id,{date:'2026-06-02',hours:2});
+  assert.equal(await s.work.hours(st.id),5);
+  const due=await s.pay.vacationDue(st.id); assert.equal(due.amount,6000);
+  assert.equal(await s.work.hours(st.id,{from:'2026-06-02'}),2,'fenêtre temporelle');
+});
+await test('settle compose payment (payout)', async()=>{
+  const paid=[]; const s=mk({ payment:{ async payout(p){paid.push(p);} } });
+  const st=await s.staff.create({userId:'u1',hourlyRate:1000}); await s.work.log(st.id,{hours:2});
+  const r=await s.pay.settle(st.id); assert.equal(r.amount,2000); assert.equal(paid[0].amount,2000);
+});
+await test('withPerson fusionne le profil @mostajs/users', async()=>{
+  const users=createUsers({ repositories:userRepos() }); const u=await users.create({firstName:'Mme',lastName:'X'});
+  const s=mk({ users }); const st=await s.staff.create({userId:u.id,type:'teacher'});
+  const full=await s.staff.withPerson(st.id); assert.equal(full.person.name,'Mme X');
+});
+await test('disponibilités (set/get)', async()=>{
+  const s=mk(); const st=await s.staff.create({userId:'u1'});
+  await s.staff.setAvailability(st.id,[{day:'samedi',from:'14:00',to:'17:00'}]);
+  assert.equal((await s.staff.getAvailability(st.id))[0].day,'samedi');
+});
+console.log(`\n✅ @mostajs/staff — ${pass} tests OK`);