nodebb-plugin-onekite-calendar 2.0.10 → 2.0.12

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog – calendar-onekite
 
+## 1.3.5
+- ACP : ajout d’un paramètre « Location longue durée (jours) pour validateurs ». Si une réservation faite par un validateur dépasse ce nombre de jours, elle redevient payante et suit le workflow normal (demande → validation → paiement HelloAsso). Mets 0 pour conserver le comportement « toujours gratuit ».
+
+## 1.3.4
+- Réservations gratuites (validateurs) : ne sont plus comptées comme chiffre d’affaires dans la comptabilisation. Elles apparaissent désormais sur une ligne séparée « Sorties gratuites » (et sont marquées (gratuit) dans le détail).
+
+## 1.3.3
+- Comptabilité : les réservations « auto-checkées » (réservations faites par un validateur) recalculent désormais le total côté serveur (catalogue HelloAsso × nb jours calendaires) afin d’être comptabilisées correctement.
+
+## 1.3.2
+- Les membres validateurs (ceux qui peuvent valider/supprimer une demande) voient leurs propres réservations passer directement en statut payé/checked (pas de workflow paiement).
+- UI : message de succès adapté (réservation confirmée).
+
+## 1.3.1
+- ACP : ajout de 2 actions rapides dans l’onglet Maintenance : « Tout mettre en maintenance » et « Tout enlever de maintenance » (avec audit).
+
+## 1.3.0
+- Maintenance (sans dates) : blocage manuel ON/OFF par matériel (ACP + API). Les matériels en maintenance sont grisés et affichés comme : 🔧 Nom (en maintenance).
+- Audit : journal des actions (demande, validation, refus, annulation, maintenance) avec consultation et purge par année (ACP + API).
+
+## 1.2.18
+- API events + anti double booking : les tests de chevauchement utilisent désormais en priorité startDate/endDate (YYYY-MM-DD) quand disponibles (logique calendaire pure, endDate exclusive). Cela supprime définitivement les faux chevauchements liés aux timestamps/fuseaux/DST, notamment sur mobile et « Durée rapide ».
+
 ## 1.2.17
 - Modale réservation : la requête de disponibilité initiale utilise aussi des dates calendaires (YYYY-MM-DD) au lieu de startStr/endStr/toISOString(), ce qui corrige le grisé erroné (mobile + durée rapide).
 
@@ -72,3 +95,8 @@
 - Validation / refus des demandes depuis l’ACP
 - Notifications Discord
 - Intégration paiements HelloAsso
+
+## 1.2.19
+- Mobile: ajout d’un bouton flottant (FAB) sur la page calendrier uniquement.
+- Le FAB ouvre une mini-modale de sélection de dates (dd/mm/yyyy) puis ouvre la modale standard de réservation.
+- Le FAB est automatiquement retiré quand on navigue hors de la page calendrier.

package/lib/admin.js

@@ -404,6 +404,7 @@ admin.getAccounting = async function (req, res) {
   const ids = await dbLayer.listAllReservationIds(100000);
   const rows = [];
   const byItem = new Map();
+  let freeCount = 0;
 
   for (const rid of ids) {
     const r = await dbLayer.getReservation(rid);
@@ -418,10 +419,13 @@ admin.getAccounting = async function (req, res) {
       ? r.itemNames
       : (r.itemName ? [r.itemName] : []);
 
-    const total = Number(r.total) || 0;
+    const isFree = !!r.isFree;
+    const total = isFree ? 0 : (Number(r.total) || 0);
     const startDate = formatFR(r.start);
     const endDate = formatFR(r.end);
 
+    if (isFree) freeCount += 1;
+
     rows.push({
       rid: r.rid,
       uid: r.uid,
@@ -433,19 +437,26 @@ admin.getAccounting = async function (req, res) {
       items: itemNames,
       total,
       paidAt: r.paidAt || '',
+      isFree,
     });
 
-    for (const name of itemNames) {
-      const key = String(name || '').trim();
-      if (!key) continue;
-      const cur = byItem.get(key) || { item: key, count: 0, total: 0 };
-      cur.count += 1;
-      cur.total += total;
-      byItem.set(key, cur);
+    // Only count paid (non-free) reservations into revenue by item.
+    if (!isFree) {
+      for (const name of itemNames) {
+        const key = String(name || '').trim();
+        if (!key) continue;
+        const cur = byItem.get(key) || { item: key, count: 0, total: 0 };
+        cur.count += 1;
+        cur.total += total;
+        byItem.set(key, cur);
+      }
     }
   }
 
   const summary = Array.from(byItem.values()).sort((a, b) => b.count - a.count);
+  if (freeCount > 0) {
+    summary.push({ item: 'Sorties gratuites', count: freeCount, total: 0, isFree: true });
+  }
   rows.sort((a, b) => parseInt(a.start, 10) - parseInt(b.start, 10));
 
   return res.json({
@@ -477,7 +488,7 @@ admin.exportAccountingCsv = async function (req, res) {
     return s;
   };
   const lines = [];
-  lines.push(['rid', 'username', 'uid', 'start', 'end', 'items', 'total', 'paidAt'].map(escape).join(','));
+  lines.push(['rid', 'username', 'uid', 'start', 'end', 'items', 'total', 'paidAt', 'isFree'].map(escape).join(','));
   for (const r of payload.rows || []) {
     lines.push([
       r.rid,
@@ -488,6 +499,7 @@ admin.exportAccountingCsv = async function (req, res) {
       (Array.isArray(r.items) ? r.items.join(' | ') : ''),
       (Number(r.total) || 0).toFixed(2),
       r.paidAt ? new Date(parseInt(r.paidAt, 10)).toISOString() : '',
+      r.isFree ? '1' : '0',
     ].map(escape).join(','));
   }
   const csv = lines.join('\n');

package/lib/api.js

@@ -326,6 +326,35 @@ async function canValidate(uid, settings) {
   return false;
 }
 
+async function canModerate(uid) {
+  const settings = await meta.settings.get('calendar-onekite');
+  return await canValidate(uid, settings);
+}
+
+async function auditLog(action, actorUid, payload) {
+  try {
+    const uid = actorUid ? parseInt(actorUid, 10) : 0;
+    let actorUsername = '';
+    if (uid) {
+      try {
+        const u = await user.getUserFields(uid, ['username']);
+        actorUsername = (u && u.username) ? String(u.username) : '';
+      } catch (e) {}
+    }
+    const ts = Date.now();
+    const year = new Date(ts).getFullYear();
+    await dbLayer.addAuditEntry(Object.assign({
+      ts,
+      year,
+      action: String(action || ''),
+      actorUid: uid,
+      actorUsername,
+    }, payload || {}));
+  } catch (e) {
+    // never block user flows on audit
+  }
+}
+
 async function canCreateSpecial(uid, settings) {
   if (!uid) return false;
   try {
@@ -445,8 +474,17 @@ function computeEtag(payload) {
 }
 
 api.getEvents = async function (req, res) {
-  const startTs = toTs(req.query.start) || 0;
-  const endTs = toTs(req.query.end) || (Date.now() + 365 * 24 * 3600 * 1000);
+  const qStartRaw = (req && req.query && req.query.start !== undefined) ? String(req.query.start).trim() : '';
+  const qEndRaw = (req && req.query && req.query.end !== undefined) ? String(req.query.end).trim() : '';
+
+  // If the client provides date-only strings (YYYY-MM-DD), prefer purely calendar-based
+  // overlap checks. This avoids any dependency on server timezone, user timezone, DST,
+  // or how JS Date() parses inputs.
+  const qStartYmd = (/^\d{4}-\d{2}-\d{2}$/.test(qStartRaw)) ? qStartRaw : null;
+  const qEndYmd = (/^\d{4}-\d{2}-\d{2}$/.test(qEndRaw)) ? qEndRaw : null;
+
+  const startTs = toTs(qStartRaw) || 0;
+  const endTs = toTs(qEndRaw) || (Date.now() + 365 * 24 * 3600 * 1000);
 
   const settings = await meta.settings.get('calendar-onekite');
   const canMod = req.uid ? await canValidate(req.uid, settings) : false;
@@ -494,9 +532,19 @@ api.getEvents = async function (req, res) {
     }
     // Only show active statuses
     if (!['pending', 'awaiting_payment', 'paid'].includes(r.status)) continue;
-    const rStart = parseInt(r.start, 10);
-    const rEnd = parseInt(r.end, 10);
-    if (!(rStart < endTs && startTs < rEnd)) continue; // overlap check
+    // Overlap check
+    // Prefer date-only strings (YYYY-MM-DD) for 100% reliable calendar-day logic.
+    const rStartYmd = (r.startDate && /^\d{4}-\d{2}-\d{2}$/.test(String(r.startDate))) ? String(r.startDate) : null;
+    const rEndYmd = (r.endDate && /^\d{4}-\d{2}-\d{2}$/.test(String(r.endDate))) ? String(r.endDate) : null;
+
+    if (qStartYmd && qEndYmd && rStartYmd && rEndYmd) {
+      // endDate is EXCLUSIVE (FullCalendar rule): overlap iff aStart < bEnd && bStart < aEnd
+      if (!(rStartYmd < qEndYmd && qStartYmd < rEndYmd)) continue;
+    } else {
+      const rStart = parseInt(r.start, 10);
+      const rEnd = parseInt(r.end, 10);
+      if (!(rStart < endTs && startTs < rEnd)) continue;
+    }
     const evs = eventsFor(r);
     for (const ev of evs) {
       const p = ev.extendedProps || {};
@@ -763,7 +811,18 @@ api.getItems = async function (req, res) {
     price: typeof it.price === 'number' ? it.price : 0,
   })).filter(it => it.id && it.name);
 
-  res.json(normalized);
+  // Maintenance (simple ON/OFF per item)
+  let maint = new Set();
+  try {
+    const ids = await dbLayer.listMaintenanceItemIds(20000);
+    maint = new Set((ids || []).map(String));
+  } catch (e) {}
+
+  const out = normalized.map((it) => Object.assign({}, it, {
+    maintenance: maint.has(String(it.id)),
+  }));
+
+  res.json(out);
 };
 
 api.createReservation = async function (req, res) {
@@ -775,6 +834,8 @@ api.createReservation = async function (req, res) {
   const ok = await canRequest(uid, settings, startPreview);
   if (!ok) return res.status(403).json({ error: 'not-allowed' });
 
+  const isValidator = await canValidate(uid, settings);
+
   const startRaw = req.body.start;
   const endRaw = req.body.end;
   const start = parseInt(toTs(startRaw), 10);
@@ -788,6 +849,23 @@ api.createReservation = async function (req, res) {
   const startDate = (typeof startRaw === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(startRaw.trim())) ? startRaw.trim() : null;
   const endDate = (typeof endRaw === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(endRaw.trim())) ? endRaw.trim() : null;
 
+  // Validators can create "free" reservations that skip the payment workflow.
+  // However, long rentals should follow the normal paid workflow.
+  // Setting: validatorFreeMaxDays (days, endDate exclusive). If empty/0 => always free.
+  let validatorFreeMaxDays = 0;
+  try {
+    const v = parseInt(String(settings.validatorFreeMaxDays || '').trim(), 10);
+    validatorFreeMaxDays = Number.isFinite(v) ? v : 0;
+  } catch (e) {
+    validatorFreeMaxDays = 0;
+  }
+
+  // Reliable calendar-day count (endDate is EXCLUSIVE)
+  const nbDays = (startDate && endDate) ? (calendarDaysExclusiveYmd(startDate, endDate) || 1) : Math.max(1, Math.round((end - start) / (24 * 60 * 60 * 1000)));
+
+  // A validator is "free" only if the rental duration is within the configured threshold.
+  const isValidatorFree = !!isValidator && (validatorFreeMaxDays <= 0 || nbDays <= validatorFreeMaxDays);
+
   // Business rule: a reservation cannot start on the current day or in the past.
   // We compare against server-local midnight. (Front-end also prevents it.)
   try {
@@ -814,6 +892,19 @@ api.createReservation = async function (req, res) {
     return res.status(400).json({ error: 'missing-fields' });
   }
 
+  // Maintenance block (simple ON/OFF, no dates): reject if any selected item is in maintenance.
+  try {
+    const maintIds = new Set(((await dbLayer.listMaintenanceItemIds(20000)) || []).map(String));
+    const blockedByMaintenance = itemIds.filter((id) => maintIds.has(String(id)));
+    if (blockedByMaintenance.length) {
+      return res.status(409).json({
+        error: 'in-maintenance',
+        itemIds: blockedByMaintenance,
+        message: "Un ou plusieurs matériels sont en maintenance.",
+      });
+    }
+  } catch (e) {}
+
   // Prevent double booking: block if any selected item overlaps with an active reservation
   const blocking = new Set(['pending', 'awaiting_payment', 'paid']);
   const wideStart2 = Math.max(0, start - 366 * 24 * 3600 * 1000);
@@ -822,9 +913,16 @@ api.createReservation = async function (req, res) {
   const existingRows = await dbLayer.getReservations(candidateIds);
   for (const existing of (existingRows || [])) {
     if (!existing || !blocking.has(existing.status)) continue;
-    const exStart = parseInt(existing.start, 10);
-    const exEnd = parseInt(existing.end, 10);
-    if (!(exStart < end && start < exEnd)) continue;
+    const exStartYmd = (existing.startDate && /^\d{4}-\d{2}-\d{2}$/.test(String(existing.startDate))) ? String(existing.startDate) : null;
+    const exEndYmd = (existing.endDate && /^\d{4}-\d{2}-\d{2}$/.test(String(existing.endDate))) ? String(existing.endDate) : null;
+    if (startDate && endDate && exStartYmd && exEndYmd) {
+      // endDate is EXCLUSIVE: overlap iff aStart < bEnd && bStart < aEnd
+      if (!(exStartYmd < endDate && startDate < exEndYmd)) continue;
+    } else {
+      const exStart = parseInt(existing.start, 10);
+      const exEnd = parseInt(existing.end, 10);
+      if (!(exStart < end && start < exEnd)) continue;
+    }
     const exItemIds = Array.isArray(existing.itemIds) ? existing.itemIds : (existing.itemId ? [existing.itemId] : []);
     const shared = exItemIds.filter(x => itemIds.includes(String(x)));
     if (shared.length) {
@@ -857,14 +955,40 @@ api.createReservation = async function (req, res) {
     end,
     startDate,
     endDate,
-    status: 'pending',
+    status: isValidatorFree ? 'paid' : 'pending',
     createdAt: now,
-    total: isNaN(total) ? 0 : total,
+    paidAt: isValidatorFree ? now : 0,
+    approvedBy: isValidatorFree ? uid : 0,
+    // total is used for accounting (paid reservations).
+    // Validator self-reservations are FREE (no payment required) and must not be
+    // counted as revenue.
+    isFree: !!isValidatorFree,
+    total: isValidatorFree ? 0 : (isNaN(total) ? 0 : total),
   };
 
+  // NOTE: We intentionally do NOT compute a monetary total for validator self-reservations.
+  // Those are free "sorties" and are tracked separately in the accounting view.
+
   // Save
   await dbLayer.saveReservation(resv);
 
+  // Audit
+  await auditLog(isValidatorFree ? 'reservation_self_checked' : 'reservation_requested', uid, {
+    targetType: 'reservation',
+    targetId: String(resv.rid),
+    uid: Number(uid) || 0,
+    requesterUid: Number(uid) || 0,
+    requesterUsername: username || '',
+    itemIds: resv.itemIds || [],
+    itemNames: resv.itemNames || [],
+    startDate: resv.startDate || '',
+    endDate: resv.endDate || '',
+    status: resv.status,
+  });
+
+  if (!isValidatorFree) {
+
+
   // Notify groups by email (NodeBB emailer config)
   try {
     const notifyGroups = (settings.notifyGroups || '').split(',').map(s => s.trim()).filter(Boolean);
@@ -931,7 +1055,9 @@ api.createReservation = async function (req, res) {
     });
   } catch (e) {}
 
-  res.json({ ok: true, rid });
+  }
+
+  res.json({ ok: true, rid, status: resv.status, autoPaid: !!isValidatorFree });
 };
 
 // Validator actions (from calendar popup)
@@ -1048,6 +1174,18 @@ api.approveReservation = async function (req, res) {
 
   await dbLayer.saveReservation(r);
 
+  await auditLog('reservation_approved', uid, {
+    targetType: 'reservation',
+    targetId: String(rid),
+    reservationUid: Number(r.uid) || 0,
+    reservationUsername: String(r.username || ''),
+    itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+    itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+    startDate: r.startDate || '',
+    endDate: r.endDate || '',
+    status: r.status,
+  });
+
   // Email requester
   const requesterUid = parseInt(r.uid, 10);
   const requester = await user.getUserFields(requesterUid, ['username']);
@@ -1103,6 +1241,19 @@ api.refuseReservation = async function (req, res) {
   }
   await dbLayer.saveReservation(r);
 
+  await auditLog('reservation_refused', uid, {
+    targetType: 'reservation',
+    targetId: String(rid),
+    reservationUid: Number(r.uid) || 0,
+    reservationUsername: String(r.username || ''),
+    itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+    itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+    startDate: r.startDate || '',
+    endDate: r.endDate || '',
+    reason: r.refusedReason || '',
+    status: r.status,
+  });
+
   const requesterUid2 = parseInt(r.uid, 10);
   const requester = await user.getUserFields(requesterUid2, ['username']);
   if (requesterUid2) {
@@ -1159,6 +1310,18 @@ api.cancelReservation = async function (req, res) {
 
   await dbLayer.saveReservation(r);
 
+  await auditLog('reservation_cancelled', uid, {
+    targetType: 'reservation',
+    targetId: String(rid),
+    reservationUid: Number(r.uid) || 0,
+    reservationUsername: String(r.username || ''),
+    itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+    itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+    startDate: r.startDate || '',
+    endDate: r.endDate || '',
+    status: r.status,
+  });
+
   // Discord webhook (optional)
   try {
     await discord.notifyReservationCancelled(settings, {
@@ -1198,4 +1361,98 @@ api.cancelReservation = async function (req, res) {
   return res.json({ ok: true, status: 'cancelled' });
 };
 
+// --------------------
+// Maintenance (simple ON/OFF)
+// --------------------
+
+api.getMaintenance = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const ids = await dbLayer.listMaintenanceItemIds(20000);
+  return res.json({ itemIds: (ids || []).map(String) });
+};
+
+api.setMaintenance = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const itemId = String(req.params.itemId || '').trim();
+  if (!itemId) return res.status(400).json({ error: 'missing-itemId' });
+  const enabled = !!(req.body && (req.body.enabled === true || req.body.enabled === '1' || req.body.enabled === 1));
+  await dbLayer.setItemMaintenance(itemId, enabled);
+  await auditLog(enabled ? 'maintenance_on' : 'maintenance_off', uid, {
+    targetType: 'item',
+    targetId: itemId,
+  });
+  return res.json({ ok: true, itemId, enabled });
+};
+
+// Bulk toggle: enable/disable maintenance for ALL catalog items.
+// Uses the same permission as validate/delete.
+api.setMaintenanceAll = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+
+  const enabled = !!(req.body && (req.body.enabled === true || req.body.enabled === '1' || req.body.enabled === 1));
+
+  // When enabling, we need the current catalog IDs (HelloAsso shop)
+  let catalogIds = [];
+  if (enabled) {
+    const settings = await meta.settings.get('calendar-onekite');
+    const env = settings.helloassoEnv || 'prod';
+    const token = await helloasso.getAccessToken({
+      env,
+      clientId: settings.helloassoClientId,
+      clientSecret: settings.helloassoClientSecret,
+    });
+    if (!token) {
+      return res.status(400).json({ error: 'helloasso-token-missing' });
+    }
+    const year = new Date().getFullYear();
+    const { items: catalog } = await helloasso.listCatalogItems({
+      env,
+      token,
+      organizationSlug: settings.helloassoOrganizationSlug,
+      formType: settings.helloassoFormType,
+      formSlug: autoFormSlugForYear(year),
+    });
+    catalogIds = (catalog || []).map((it) => it && it.id).filter(Boolean).map(String);
+  }
+
+  const result = await dbLayer.setAllMaintenance(enabled, catalogIds);
+  await auditLog(enabled ? 'maintenance_all_on' : 'maintenance_all_off', uid, {
+    targetType: 'maintenance',
+    targetId: enabled ? 'all_on' : 'all_off',
+    count: result && typeof result.count === 'number' ? result.count : (enabled ? catalogIds.length : 0),
+  });
+  return res.json(Object.assign({ ok: true, enabled }, result || {}));
+};
+
+// --------------------
+// Audit
+// --------------------
+
+api.getAudit = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const year = Number((req.query && req.query.year) || new Date().getFullYear());
+  const limit = Math.min(500, Math.max(1, Number((req.query && req.query.limit) || 200)));
+  const entries = await dbLayer.getAuditEntriesByYear(year, limit);
+  return res.json({ year, entries: entries || [] });
+};
+
+api.purgeAudit = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const year = Number((req.body && req.body.year) || 0);
+  if (!year) return res.status(400).json({ error: 'missing-year' });
+  const result = await dbLayer.purgeAuditYear(year);
+  await auditLog('audit_purge_year', uid, { targetType: 'audit', targetId: String(year), removed: result && result.removed ? result.removed : 0 });
+  return res.json(result || { ok: true });
+};
+
 module.exports = api;

package/lib/db.js

@@ -10,6 +10,13 @@ const KEY_CHECKOUT_INTENT_TO_RID = 'calendar-onekite:helloasso:checkoutIntentToR
 const KEY_SPECIAL_ZSET = 'calendar-onekite:special';
 const KEY_SPECIAL_OBJ = (eid) => `calendar-onekite:special:${eid}`;
 
+// Maintenance (simple ON/OFF per item, no dates)
+const KEY_MAINTENANCE_ZSET = 'calendar-onekite:maintenance:itemIds';
+
+// Audit log (partitioned by year)
+const KEY_AUDIT_ZSET = (year) => `calendar-onekite:audit:${year}`;
+const KEY_AUDIT_OBJ = (id) => `calendar-onekite:audit:entry:${id}`;
+
 // Helpers
 function reservationKey(rid) {
   return KEY_OBJ(rid);
@@ -71,10 +78,106 @@ async function listAllReservationIds(limit = 5000) {
   return await db.getSortedSetRange(KEY_ZSET, 0, limit - 1);
 }
 
+// --------------------
+// Maintenance
+// --------------------
+
+async function listMaintenanceItemIds(limit = 10000) {
+  return await db.getSortedSetRange(KEY_MAINTENANCE_ZSET, 0, Math.max(0, limit - 1));
+}
+
+async function isItemInMaintenance(itemId) {
+  if (!itemId) return false;
+  try {
+    // NodeBB DB returns 1/0 for isSortedSetMember
+    if (typeof db.isSortedSetMember === 'function') {
+      return !!(await db.isSortedSetMember(KEY_MAINTENANCE_ZSET, String(itemId)));
+    }
+  } catch (e) {}
+  const ids = await listMaintenanceItemIds(20000);
+  return Array.isArray(ids) ? ids.map(String).includes(String(itemId)) : false;
+}
+
+async function setItemMaintenance(itemId, enabled) {
+  const id = String(itemId || '').trim();
+  if (!id) return;
+  if (enabled) {
+    await db.sortedSetAdd(KEY_MAINTENANCE_ZSET, 0, id);
+  } else {
+    await db.sortedSetRemove(KEY_MAINTENANCE_ZSET, id);
+  }
+}
+
+async function setAllMaintenance(enabled, itemIds) {
+  // Clear set first (fast)
+  await db.delete(KEY_MAINTENANCE_ZSET);
+  if (!enabled) {
+    return { count: 0 };
+  }
+  const ids = Array.isArray(itemIds) ? itemIds.map(String).filter(Boolean) : [];
+  // Add back all ids
+  for (const id of ids) {
+    await db.sortedSetAdd(KEY_MAINTENANCE_ZSET, 0, id);
+  }
+  return { count: ids.length };
+}
+
+// --------------------
+// Audit
+// --------------------
+
+async function addAuditEntry(entry) {
+  const e = Object.assign({}, entry || {});
+  const ts = Number(e.ts) || Date.now();
+  const year = Number(e.year) || new Date(ts).getFullYear();
+  e.ts = ts;
+  e.year = year;
+  const id = e.id ? String(e.id) : `${ts}-${Math.random().toString(16).slice(2)}`;
+  e.id = id;
+  await db.setObject(KEY_AUDIT_OBJ(id), e);
+  await db.sortedSetAdd(KEY_AUDIT_ZSET(year), ts, id);
+  return e;
+}
+
+async function listAuditEntryIdsByYear(year, start = 0, stop = 200) {
+  const y = Number(year) || new Date().getFullYear();
+  return await db.getSortedSetRevRange(KEY_AUDIT_ZSET(y), start, stop);
+}
+
+async function getAuditEntriesByYear(year, limit = 200) {
+  const ids = await listAuditEntryIdsByYear(year, 0, Math.max(0, (Number(limit) || 200) - 1));
+  if (!ids || !ids.length) return [];
+  const keys = ids.map((id) => KEY_AUDIT_OBJ(id));
+  const rows = await db.getObjects(keys);
+  // Align with ids order
+  return (rows || []).map((row, idx) => row ? Object.assign({ id: String(ids[idx]) }, row) : null).filter(Boolean);
+}
+
+async function purgeAuditYear(year) {
+  const y = Number(year);
+  if (!y) return { ok: false, removed: 0 };
+  const ids = await db.getSortedSetRange(KEY_AUDIT_ZSET(y), 0, -1);
+  const keys = (ids || []).map((id) => KEY_AUDIT_OBJ(id));
+  if (keys.length) {
+    // Batch delete objects when possible
+    if (typeof db.deleteAll === 'function') {
+      await db.deleteAll(keys);
+    } else {
+      for (const k of keys) {
+        // eslint-disable-next-line no-await-in-loop
+        await db.delete(k);
+      }
+    }
+  }
+  await db.delete(KEY_AUDIT_ZSET(y));
+  return { ok: true, removed: (ids || []).length };
+}
+
 module.exports = {
   KEY_ZSET,
   KEY_SPECIAL_ZSET,
   KEY_CHECKOUT_INTENT_TO_RID,
+  KEY_MAINTENANCE_ZSET,
   getReservation,
   getReservations,
   saveReservation,
@@ -107,4 +210,15 @@ module.exports = {
   },
   listReservationIdsByStartRange,
   listAllReservationIds,
+
+  // Maintenance
+  listMaintenanceItemIds,
+  isItemInMaintenance,
+  setItemMaintenance,
+  setAllMaintenance,
+
+  // Audit
+  addAuditEntry,
+  getAuditEntriesByYear,
+  purgeAuditYear,
 };

package/lib/helloassoWebhook.js

@@ -19,6 +19,22 @@ const dbLayer = require('./db');
 const helloasso = require('./helloasso');
 const discord = require('./discord');
 
+async function auditLog(action, actorUid, payload) {
+  try {
+    const uid = actorUid ? parseInt(actorUid, 10) : 0;
+    let actorUsername = '';
+    if (uid) {
+      try {
+        const u = await user.getUserFields(uid, ['username']);
+        actorUsername = (u && u.username) ? String(u.username) : '';
+      } catch (e) {}
+    }
+    const ts = Date.now();
+    const year = new Date(ts).getFullYear();
+    await dbLayer.addAuditEntry(Object.assign({ ts, year, action, actorUid: uid, actorUsername }, payload || {}));
+  } catch (e) {}
+}
+
 const SETTINGS_KEY = 'calendar-onekite';
 
 // Replay protection: store processed payment ids.
@@ -314,6 +330,18 @@ async function handler(req, res, next) {
     }
     await dbLayer.saveReservation(r);
 
+    await auditLog('reservation_paid', 0, {
+      targetType: 'reservation',
+      targetId: String(r.rid),
+      reservationUid: Number(r.uid) || 0,
+      reservationUsername: String(r.username || ''),
+      itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+      itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+      startDate: r.startDate || '',
+      endDate: r.endDate || '',
+      paymentId: r.paymentId || '',
+    });
+
     // Real-time notify: refresh calendars for all viewers (owner + validators/admins)
     try {
       if (io && io.sockets && typeof io.sockets.emit === 'function') {

package/library.js

@@ -66,6 +66,13 @@ Plugin.init = async function (params) {
   router.get('/api/v3/plugins/calendar-onekite/items', ...publicExpose, api.getItems);
   router.get('/api/v3/plugins/calendar-onekite/capabilities', ...publicExpose, api.getCapabilities);
 
+  // Maintenance / audit (restricted to validator groups)
+  router.get('/api/v3/plugins/calendar-onekite/maintenance', ...publicExpose, api.getMaintenance);
+  router.put('/api/v3/plugins/calendar-onekite/maintenance', ...publicExpose, api.setMaintenanceAll);
+  router.put('/api/v3/plugins/calendar-onekite/maintenance/:itemId', ...publicExpose, api.setMaintenance);
+  router.get('/api/v3/plugins/calendar-onekite/audit', ...publicExpose, api.getAudit);
+  router.post('/api/v3/plugins/calendar-onekite/audit/purge', ...publicExpose, api.purgeAudit);
+
   router.post('/api/v3/plugins/calendar-onekite/reservations', ...publicExpose, api.createReservation);
   router.get('/api/v3/plugins/calendar-onekite/reservations/:rid', ...publicExpose, api.getReservationDetails);
   router.put('/api/v3/plugins/calendar-onekite/reservations/:rid/approve', ...publicExpose, api.approveReservation);