Volunteer rosters: roles, sign-ups, swaps, QR check-in, kids-room duty (backend)
Serving roles per event or session, sign-ups and assigning with an overlap check, swaps that happen on accept (notify recipients emailed), QR and manual check-in (kids-room roles start rostered duty), optional free volunteer ticket, day-before reminder job, hours served, privacy hooks. The kids check-in and volunteer tickets are left out of public event pages and public registration. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
-- CreateEnum
|
||||
CREATE TYPE "VolunteerSwapStatus" AS ENUM ('open', 'accepted', 'cancelled');
|
||||
|
||||
-- AlterEnum
|
||||
-- This migration adds more than one value to an enum.
|
||||
-- With PostgreSQL versions 11 and earlier, this is not possible
|
||||
-- in a single migration. This can be worked around by creating
|
||||
-- multiple migrations, each migration adding only one value to
|
||||
-- the enum.
|
||||
|
||||
|
||||
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_settings_updated';
|
||||
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_roles_changed';
|
||||
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_assigned';
|
||||
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_removed';
|
||||
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_checked_in_manual';
|
||||
|
||||
-- AlterTable
|
||||
ALTER TABLE "Event" ADD COLUMN "volunteerCheckInToken" TEXT,
|
||||
ADD COLUMN "volunteerOptionId" TEXT;
|
||||
|
||||
-- AlterTable
|
||||
ALTER TABLE "KidsRoomDuty" ADD COLUMN "fromRoster" BOOLEAN NOT NULL DEFAULT false;
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "ServingRole" (
|
||||
"id" TEXT NOT NULL,
|
||||
"eventId" TEXT NOT NULL,
|
||||
"sessionId" TEXT,
|
||||
"name" TEXT NOT NULL,
|
||||
"description" TEXT,
|
||||
"needed" INTEGER NOT NULL DEFAULT 1,
|
||||
"startsAt" TIMESTAMP(3),
|
||||
"endsAt" TIMESTAMP(3),
|
||||
"kidsRoomId" TEXT,
|
||||
"order" INTEGER NOT NULL DEFAULT 0,
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updatedAt" TIMESTAMP(3) NOT NULL,
|
||||
|
||||
CONSTRAINT "ServingRole_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "VolunteerSlot" (
|
||||
"id" TEXT NOT NULL,
|
||||
"roleId" TEXT NOT NULL,
|
||||
"userId" TEXT NOT NULL,
|
||||
"assignedById" TEXT,
|
||||
"checkedInAt" TIMESTAMP(3),
|
||||
"checkedInById" TEXT,
|
||||
"checkInMethod" TEXT,
|
||||
"remindedAt" TIMESTAMP(3),
|
||||
"registrationId" TEXT,
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
|
||||
CONSTRAINT "VolunteerSlot_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "VolunteerSwap" (
|
||||
"id" TEXT NOT NULL,
|
||||
"slotId" TEXT,
|
||||
"roleId" TEXT NOT NULL,
|
||||
"fromUserId" TEXT,
|
||||
"toUserId" TEXT,
|
||||
"note" TEXT,
|
||||
"status" "VolunteerSwapStatus" NOT NULL DEFAULT 'open',
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"resolvedAt" TIMESTAMP(3),
|
||||
|
||||
CONSTRAINT "VolunteerSwap_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateIndex
|
||||
CREATE INDEX "ServingRole_eventId_sessionId_idx" ON "ServingRole"("eventId", "sessionId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE INDEX "ServingRole_kidsRoomId_idx" ON "ServingRole"("kidsRoomId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE INDEX "VolunteerSlot_userId_idx" ON "VolunteerSlot"("userId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE INDEX "VolunteerSlot_registrationId_idx" ON "VolunteerSlot"("registrationId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "VolunteerSlot_roleId_userId_key" ON "VolunteerSlot"("roleId", "userId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE INDEX "VolunteerSwap_roleId_status_idx" ON "VolunteerSwap"("roleId", "status");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE INDEX "VolunteerSwap_slotId_idx" ON "VolunteerSwap"("slotId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "Event_volunteerCheckInToken_key" ON "Event"("volunteerCheckInToken");
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "ServingRole" ADD CONSTRAINT "ServingRole_eventId_fkey" FOREIGN KEY ("eventId") REFERENCES "Event"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "ServingRole" ADD CONSTRAINT "ServingRole_sessionId_fkey" FOREIGN KEY ("sessionId") REFERENCES "EventSession"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "ServingRole" ADD CONSTRAINT "ServingRole_kidsRoomId_fkey" FOREIGN KEY ("kidsRoomId") REFERENCES "AllocationGroup"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_roleId_fkey" FOREIGN KEY ("roleId") REFERENCES "ServingRole"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_assignedById_fkey" FOREIGN KEY ("assignedById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_checkedInById_fkey" FOREIGN KEY ("checkedInById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_registrationId_fkey" FOREIGN KEY ("registrationId") REFERENCES "Registration"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_slotId_fkey" FOREIGN KEY ("slotId") REFERENCES "VolunteerSlot"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_roleId_fkey" FOREIGN KEY ("roleId") REFERENCES "ServingRole"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_fromUserId_fkey" FOREIGN KEY ("fromUserId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_toUserId_fkey" FOREIGN KEY ("toUserId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
|
||||
@@ -158,6 +158,13 @@ model User {
|
||||
kidsAlertsRaised KidsAlert[]
|
||||
kidsRoomDuties KidsRoomDuty[]
|
||||
|
||||
// Volunteer rosters (1.46.0)
|
||||
volunteerSlots VolunteerSlot[] @relation("VolunteerSlotUser")
|
||||
volunteersAssigned VolunteerSlot[] @relation("VolunteerSlotAssignedBy")
|
||||
volunteersCheckedIn VolunteerSlot[] @relation("VolunteerSlotCheckedInBy")
|
||||
swapsAsked VolunteerSwap[] @relation("VolunteerSwapFrom")
|
||||
swapsTaken VolunteerSwap[] @relation("VolunteerSwapTo")
|
||||
|
||||
@@index([homeCampusId])
|
||||
}
|
||||
|
||||
@@ -304,6 +311,14 @@ model Event {
|
||||
kidsCheckIns KidsCheckIn[]
|
||||
kidsAlerts KidsAlert[]
|
||||
|
||||
// Volunteer rosters (1.46.0): serving roles for the event or one of its sessions. When
|
||||
// `volunteerOptionId` is set (a main ticket of this event; off by default), each volunteer
|
||||
// gets a free place on it. `volunteerCheckInToken` is in the check-in QR code volunteers scan
|
||||
// on the day (made the first time the QR code is shown). Plain id, checked in utils/volunteers.js.
|
||||
servingRoles ServingRole[]
|
||||
volunteerOptionId String?
|
||||
volunteerCheckInToken String? @unique
|
||||
|
||||
@@index([createdById])
|
||||
@@index([closedById])
|
||||
@@index([reopenedById])
|
||||
@@ -399,6 +414,7 @@ model Registration {
|
||||
bundleApplications RegistrationBundle[]
|
||||
attendees Attendee[]
|
||||
waitlistEntries WaitlistEntry[]
|
||||
volunteerSlots VolunteerSlot[]
|
||||
|
||||
@@index([userId])
|
||||
@@index([eventId])
|
||||
@@ -678,6 +694,11 @@ enum AdminAuditAction {
|
||||
kids_wrong_code
|
||||
kids_custody_notes_changed
|
||||
kids_offline_sync
|
||||
volunteer_settings_updated
|
||||
volunteer_roles_changed
|
||||
volunteer_assigned
|
||||
volunteer_removed
|
||||
volunteer_checked_in_manual
|
||||
}
|
||||
|
||||
// Append-only audit trail for admin/supervisor-initiated actions with money or
|
||||
@@ -1364,6 +1385,7 @@ model AllocationGroup {
|
||||
kidsCheckIns KidsCheckIn[]
|
||||
kidsAlerts KidsAlert[]
|
||||
kidsDuties KidsRoomDuty[]
|
||||
servingRoles ServingRole[]
|
||||
|
||||
@@index([setId])
|
||||
@@index([leaderUserId])
|
||||
@@ -1639,6 +1661,7 @@ model EventSession {
|
||||
reminders SessionReminderLog[]
|
||||
registrationOptions RegistrationOption[]
|
||||
waitlistEntries WaitlistEntry[]
|
||||
servingRoles ServingRole[]
|
||||
|
||||
@@index([eventId, startsAt])
|
||||
}
|
||||
@@ -2017,9 +2040,94 @@ model KidsRoomDuty {
|
||||
userId String
|
||||
startedAt DateTime @default(now())
|
||||
endedAt DateTime?
|
||||
// Volunteer rosters (1.46.0): started by a rostered volunteer checking in, not "I'm on duty".
|
||||
fromRoster Boolean @default(false)
|
||||
room AllocationGroup @relation(fields: [roomId], references: [id], onDelete: Cascade)
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@index([roomId, occasion])
|
||||
@@index([userId])
|
||||
}
|
||||
|
||||
// ─── Volunteer rosters (1.46.0) ───────────────────────────────────────────────
|
||||
|
||||
// A serving role (Welcome, Parking, Sound…) for one event — or, on a multi-session event, one
|
||||
// session — with the number of people needed. Shift times are optional (null = the session's or
|
||||
// event's times). A role linked to a kids room puts its volunteers on duty there when they check
|
||||
// in, so they count for the room's ratio.
|
||||
model ServingRole {
|
||||
id String @id @default(uuid())
|
||||
eventId String
|
||||
sessionId String?
|
||||
name String
|
||||
description String?
|
||||
needed Int @default(1)
|
||||
startsAt DateTime?
|
||||
endsAt DateTime?
|
||||
kidsRoomId String?
|
||||
order Int @default(0)
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
event Event @relation(fields: [eventId], references: [id], onDelete: Cascade)
|
||||
session EventSession? @relation(fields: [sessionId], references: [id], onDelete: Cascade)
|
||||
kidsRoom AllocationGroup? @relation(fields: [kidsRoomId], references: [id], onDelete: SetNull)
|
||||
slots VolunteerSlot[]
|
||||
swaps VolunteerSwap[]
|
||||
|
||||
@@index([eventId, sessionId])
|
||||
@@index([kidsRoomId])
|
||||
}
|
||||
|
||||
// A person serving in a role. `assignedById` is the supervisor who put them there (null = they
|
||||
// signed up). Withdrawing or being removed deletes the row; a swap moves it to the person who
|
||||
// takes it over. `registrationId` is the free volunteer place they were given, if any.
|
||||
model VolunteerSlot {
|
||||
id String @id @default(uuid())
|
||||
roleId String
|
||||
userId String
|
||||
assignedById String?
|
||||
checkedInAt DateTime?
|
||||
checkedInById String?
|
||||
// 'qr' (the volunteer scanned the check-in QR code) or 'manual' (ticked by staff)
|
||||
checkInMethod String?
|
||||
remindedAt DateTime?
|
||||
registrationId String?
|
||||
createdAt DateTime @default(now())
|
||||
role ServingRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
|
||||
user User @relation("VolunteerSlotUser", fields: [userId], references: [id], onDelete: Cascade)
|
||||
assignedBy User? @relation("VolunteerSlotAssignedBy", fields: [assignedById], references: [id], onDelete: SetNull)
|
||||
checkedInBy User? @relation("VolunteerSlotCheckedInBy", fields: [checkedInById], references: [id], onDelete: SetNull)
|
||||
registration Registration? @relation(fields: [registrationId], references: [id], onDelete: SetNull)
|
||||
swaps VolunteerSwap[]
|
||||
|
||||
@@unique([roleId, userId])
|
||||
@@index([userId])
|
||||
@@index([registrationId])
|
||||
}
|
||||
|
||||
enum VolunteerSwapStatus {
|
||||
open
|
||||
accepted
|
||||
cancelled
|
||||
}
|
||||
|
||||
// "Can't make it": the volunteer asks someone to take their place. It happens as soon as someone
|
||||
// accepts (the slot moves to them), and the event's notify recipients are told.
|
||||
model VolunteerSwap {
|
||||
id String @id @default(uuid())
|
||||
slotId String?
|
||||
roleId String
|
||||
fromUserId String?
|
||||
toUserId String?
|
||||
note String?
|
||||
status VolunteerSwapStatus @default(open)
|
||||
createdAt DateTime @default(now())
|
||||
resolvedAt DateTime?
|
||||
slot VolunteerSlot? @relation(fields: [slotId], references: [id], onDelete: SetNull)
|
||||
role ServingRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
|
||||
fromUser User? @relation("VolunteerSwapFrom", fields: [fromUserId], references: [id], onDelete: SetNull)
|
||||
toUser User? @relation("VolunteerSwapTo", fields: [toUserId], references: [id], onDelete: SetNull)
|
||||
|
||||
@@index([roleId, status])
|
||||
@@index([slotId])
|
||||
}
|
||||
|
||||
@@ -8,6 +8,7 @@ const { assertEventOpen } = require('../utils/cashupUtils');
|
||||
const { logAdminAction } = require('../utils/adminAudit');
|
||||
const { getClientIp } = require('../utils/requestUtils');
|
||||
const sessionsUtil = require('../utils/sessions');
|
||||
const { publicOptions } = require('../utils/volunteers');
|
||||
const { campusesEnabled, campusForEvent, campusWhere, resolveCampusFilter, EVENT_CAMPUS_SELECT } = require('../utils/campuses');
|
||||
const { scopeFor, canView, canManage, eventWhere: scopeEventWhere, withScope } = require('../utils/campusScope');
|
||||
|
||||
@@ -374,7 +375,8 @@ const getEvents = async (req, res) => {
|
||||
|
||||
// Compute isSoldOut per event: true when every option that has a stock limit
|
||||
// is fully sold out. Events with no limited options are never sold out.
|
||||
const withStock = await Promise.all(events.map(async ev => {
|
||||
const withStock = await Promise.all(events.map(async listed => {
|
||||
const ev = { ...listed, eventOptions: publicOptions(listed) };
|
||||
const earlyBirdEndsAt = earlyBirdEnds.get(ev.id) || null;
|
||||
try {
|
||||
// Picked-session options have per-session limits, so they never make the event sold out.
|
||||
@@ -532,6 +534,8 @@ const getEventById = async (req, res) => {
|
||||
if (!isStaffOrHigher) {
|
||||
delete event.createdBy;
|
||||
delete event.notifyRecipients;
|
||||
// The kids check-in and volunteer tickets are handed out by staff, never sold.
|
||||
event.eventOptions = publicOptions(event);
|
||||
if (event.isActive === false) {
|
||||
res.status(404);
|
||||
throw new Error('Event not found');
|
||||
|
||||
@@ -13,6 +13,7 @@ const { findAccountByContact } = require('../utils/accountMatch');
|
||||
const { ensureConsentRequests } = require('../utils/consent');
|
||||
const { takenCount } = require('../utils/stock');
|
||||
const { findOfferByToken, queueWaitlist } = require('../utils/waitlist');
|
||||
const { reservedOptionIds } = require('../utils/volunteers');
|
||||
|
||||
// Youth events: send parental consent requests for any new under-18 attendees. Runs in
|
||||
// the background so a slow mail/WhatsApp send never holds up the registration.
|
||||
@@ -237,9 +238,11 @@ const createRegistration = async (req, res) => {
|
||||
// Options are independent of each other, so resolve them concurrently. Errors are marked
|
||||
// with `.isStockError` rather than relying on shared `res.statusCode` (which would race
|
||||
// across concurrent iterations) — the outer catch always responds 400 regardless.
|
||||
// The kids check-in and volunteer tickets are handed out by staff, never sold.
|
||||
const reserved = new Set(isStaffRole(req.user?.role) ? [] : reservedOptionIds(event));
|
||||
const resolvedOptions = await Promise.all(lines.map(async (option) => {
|
||||
const eventOption = event.eventOptions.find(eo => eo.id === option.eventOptionId);
|
||||
if (!eventOption) {
|
||||
if (!eventOption || reserved.has(eventOption.id)) {
|
||||
throw new Error(`Option with ID ${option.eventOptionId} not found for this event`);
|
||||
}
|
||||
if (!option.quantity || option.quantity < 1) {
|
||||
@@ -1507,6 +1510,18 @@ const updateRegistrationOptions = async (req, res) => {
|
||||
throw new Error("Sessions are booked by registering for them — they can't be changed here.");
|
||||
}
|
||||
}
|
||||
// The kids check-in and volunteer tickets are handed out by staff: the owner can keep (or
|
||||
// lower) the places they were given, not add more.
|
||||
if (!isStaffRole(req.user.role)) {
|
||||
for (const id of reservedOptionIds(registration.event)) {
|
||||
const had = registration.registrationOptions.filter(ro => ro.eventOptionId === id).reduce((n, ro) => n + (ro.quantity || 0), 0);
|
||||
const asked = options.filter(o => o.eventOptionId === id).reduce((n, o) => n + o.quantity, 0);
|
||||
if (asked > had) {
|
||||
res.status(400);
|
||||
throw new Error('One or more options do not belong to this event');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Picked-session lines aren't edited here: leave them exactly as they are (they still
|
||||
// count towards the total due).
|
||||
|
||||
@@ -0,0 +1,269 @@
|
||||
const prisma = require('../config/db');
|
||||
const { safeErrorMessage } = require('../utils/errorUtils');
|
||||
const { logAdminAction } = require('../utils/adminAudit');
|
||||
const { getClientIp } = require('../utils/requestUtils');
|
||||
const { logDataAccess } = require('../utils/accessLog');
|
||||
const { listWhere, withScope } = require('../utils/campusScope');
|
||||
const v = require('../utils/volunteers');
|
||||
|
||||
const fail = (res, error) => res.status(error.statusCode || 400).json({ message: safeErrorMessage(error), ...(error.code && typeof error.code === 'string' && !error.code.startsWith('P') ? { code: error.code } : {}) });
|
||||
const audit = (req, action, targetType, targetId, metadata) => logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action, targetType, targetId, metadata, ip: getClientIp(req) });
|
||||
const later = p => { Promise.resolve(p).catch(() => {}); };
|
||||
const CONTACT = { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true, isActive: true };
|
||||
|
||||
// ─── My account → Serving (anyone signed in) ──────────────────────────────────
|
||||
|
||||
// @desc My shifts, cover requests I could take, and events looking for volunteers
|
||||
// @route GET /api/volunteers/me
|
||||
const getMine = async (req, res) => {
|
||||
try {
|
||||
const now = new Date();
|
||||
const [slots, cover, events] = await Promise.all([
|
||||
v.mySlots({ userId: req.user.id, now }),
|
||||
v.openSwaps({ userId: req.user.id, now }),
|
||||
v.eventsWithRoles({ now, where: { isHidden: false, goLiveAt: { lte: now } } }),
|
||||
]);
|
||||
res.json({ slots, cover, events: events.map(e => ({ id: e.id, title: e.title, startDate: e.startDate, endDate: e.endDate, location: e.location, roles: e._count.servingRoles })) });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc An event's serving roles: how full each is, and whether I'm in it
|
||||
// @route GET /api/volunteers/events/:eventId
|
||||
const getEventRoles = async (req, res) => {
|
||||
try {
|
||||
const out = await v.roster(req.params.eventId, { userId: req.user.id });
|
||||
res.json(out);
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @route POST /api/volunteers/roles/:id/sign-up
|
||||
const signUp = async (req, res) => {
|
||||
try {
|
||||
const { slot, role, event } = await v.signUp({ roleId: req.params.id, userId: req.user.id });
|
||||
// req.user has no notification preference; the message goes the way they like it.
|
||||
later(prisma.user.findUnique({ where: { id: req.user.id }, select: CONTACT }).then(user => v.signedUpMessages({ user, role, event })));
|
||||
res.status(201).json({ slotId: slot.id, ticket: !!slot.registrationId });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Withdraw from a shift (the event's notify recipients are told)
|
||||
// @route DELETE /api/volunteers/slots/:id
|
||||
const withdraw = async (req, res) => {
|
||||
try {
|
||||
const out = await v.leave({ slotId: req.params.id, userId: req.user.id });
|
||||
later(v.sendLeft(out));
|
||||
res.json({ message: 'You\'re off the roster for this shift.' });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc "Can't make it": ask the event's other volunteers to take over
|
||||
// @route POST /api/volunteers/slots/:id/swap { note? }
|
||||
const requestSwap = async (req, res) => {
|
||||
try {
|
||||
const out = await v.requestSwap({ slotId: req.params.id, userId: req.user.id, note: req.body?.note });
|
||||
if (out.created) later(v.sendSwapRequest(out));
|
||||
res.status(out.created ? 201 : 200).json({ swapId: out.swap.id });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @route DELETE /api/volunteers/swaps/:id
|
||||
const cancelSwap = async (req, res) => {
|
||||
try {
|
||||
res.json(await v.cancelSwap({ swapId: req.params.id, userId: req.user.id }));
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Take over someone's place. Happens at once; the event's notify recipients are told.
|
||||
// @route POST /api/volunteers/swaps/:id/accept
|
||||
const acceptSwap = async (req, res) => {
|
||||
try {
|
||||
const out = await v.acceptSwap({ swapId: req.params.id, userId: req.user.id });
|
||||
later(v.sendSwapAccepted(out));
|
||||
res.json({ slotId: out.slot.id, role: out.slot.role.name, event: out.event.title });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Check in by scanning the event's volunteer QR code
|
||||
// @route POST /api/volunteers/check-in { qr }
|
||||
const checkIn = async (req, res) => {
|
||||
try {
|
||||
res.json(await v.checkInWithQr({ qr: req.body?.qr, userId: req.user.id }));
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// ─── Staff: the roster on the day ─────────────────────────────────────────────
|
||||
|
||||
// @desc Events with serving roles (or upcoming, for supervisors setting them up)
|
||||
// @route GET /api/volunteers/manage/events?all=1
|
||||
const listEvents = async (req, res) => {
|
||||
try {
|
||||
const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
|
||||
const base = req.query.all === '1' && ['admin', 'supervisor'].includes(req.user.role)
|
||||
? { endDate: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) } }
|
||||
: { endDate: { gte: since }, servingRoles: { some: {} } };
|
||||
const events = await prisma.event.findMany({
|
||||
where: withScope(base, await listWhere(req)),
|
||||
select: { id: true, title: true, startDate: true, endDate: true, scheduleType: true, campusId: true, _count: { select: { servingRoles: true } } },
|
||||
orderBy: { startDate: 'asc' },
|
||||
take: 200,
|
||||
});
|
||||
res.json(events.map(e => ({ id: e.id, title: e.title, startDate: e.startDate, endDate: e.endDate, scheduleType: e.scheduleType, campusId: e.campusId, roles: e._count.servingRoles })));
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc The roster sheet: roles with their volunteers, contact details and check-ins
|
||||
// @route GET /api/volunteers/manage/events/:eventId?log=1
|
||||
const getRoster = async (req, res) => {
|
||||
try {
|
||||
const out = await v.roster(req.params.eventId, { staff: true, userId: req.user.id });
|
||||
if (req.query.log === '1') {
|
||||
logDataAccess(req, { action: 'volunteer_roster', eventId: out.event.id, records: out.roles.reduce((n, r) => n + r.volunteers.length, 0) });
|
||||
}
|
||||
res.json(out);
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc The check-in QR code volunteers scan on the day
|
||||
// @route GET /api/volunteers/manage/events/:eventId/qr
|
||||
const getQr = async (req, res) => {
|
||||
try {
|
||||
res.json(await v.checkInQr(req.params.eventId));
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @route POST /api/volunteers/manage/slots/:id/check-in { undo? }
|
||||
const checkInManual = async (req, res) => {
|
||||
try {
|
||||
const out = await v.checkInManual({ slotId: req.params.id, staffUserId: req.user.id, undo: !!req.body?.undo });
|
||||
if (out.changed) audit(req, 'volunteer_checked_in_manual', 'volunteer_slot', out.slot.id, { volunteer: out.slot.user.name, role: out.slot.role.name, undo: !!req.body?.undo });
|
||||
res.json({ slotId: out.slot.id, changed: out.changed });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// ─── Supervisors: roles, people, settings, reports ────────────────────────────
|
||||
|
||||
// @route GET /api/volunteers/manage/events/:eventId/settings
|
||||
const getSettings = async (req, res) => {
|
||||
try {
|
||||
res.json(await v.getSettings(req.params.eventId));
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Free volunteer place on/off: { optionId } ('new' adds a free "Volunteer" ticket, null = off)
|
||||
// @route PUT /api/volunteers/manage/events/:eventId/settings
|
||||
const saveSettings = async (req, res) => {
|
||||
try {
|
||||
const out = await v.saveSettings(req.params.eventId, { optionId: req.body?.optionId ?? null });
|
||||
audit(req, 'volunteer_settings_updated', 'event', out.event.id, { volunteerOptionId: out.event.volunteerOptionId });
|
||||
res.json(out);
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @route POST /api/volunteers/manage/events/:eventId/roles { name, needed, sessionId?, startsAt?, endsAt?, description?, kidsRoomId? }
|
||||
const createRole = async (req, res) => {
|
||||
try {
|
||||
const role = await v.createRole(req.params.eventId, req.body);
|
||||
audit(req, 'volunteer_roles_changed', 'serving_role', role.id, { eventId: role.eventId, created: role.name, needed: role.needed });
|
||||
res.status(201).json(role);
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @route PUT /api/volunteers/manage/roles/:id
|
||||
const updateRole = async (req, res) => {
|
||||
try {
|
||||
const role = await v.updateRole(req.params.id, req.body);
|
||||
audit(req, 'volunteer_roles_changed', 'serving_role', role.id, { eventId: role.eventId, updated: role.name, needed: role.needed });
|
||||
res.json(role);
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @route DELETE /api/volunteers/manage/roles/:id (its volunteers are told)
|
||||
const deleteRole = async (req, res) => {
|
||||
try {
|
||||
const out = await v.deleteRole(req.params.id);
|
||||
audit(req, 'volunteer_roles_changed', 'serving_role', out.role.id, { eventId: out.role.eventId, deleted: out.role.name, volunteers: out.volunteers.length });
|
||||
later(v.sendRoleDeleted(out));
|
||||
res.json({ message: 'Deleted', volunteers: out.volunteers.length });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Put someone on a role (allowed beyond the number needed); they're told
|
||||
// @route POST /api/volunteers/manage/roles/:id/assign { userId }
|
||||
const assign = async (req, res) => {
|
||||
try {
|
||||
const user = await prisma.user.findUnique({ where: { id: String(req.body?.userId || '') }, select: CONTACT });
|
||||
if (!user) throw v.volunteerError('Choose who to put on the roster.', 404);
|
||||
const { slot, role, event } = await v.signUp({ roleId: req.params.id, userId: user.id, assignedById: req.user.id });
|
||||
audit(req, 'volunteer_assigned', 'volunteer_slot', slot.id, { eventId: event.id, role: role.name, volunteer: user.name });
|
||||
if (user.isActive) later(v.signedUpMessages({ user, role, event, by: req.user.name }));
|
||||
res.status(201).json({ slotId: slot.id, ticket: !!slot.registrationId });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Take someone off a role (not after they've checked in); they're told
|
||||
// @route DELETE /api/volunteers/manage/slots/:id
|
||||
const remove = async (req, res) => {
|
||||
try {
|
||||
const out = await v.leave({ slotId: req.params.id });
|
||||
audit(req, 'volunteer_removed', 'volunteer_slot', out.slot.id, { eventId: out.event.id, role: out.slot.role.name, volunteer: out.slot.user.name });
|
||||
later(v.sendLeft({ ...out, byStaff: req.user.name }));
|
||||
res.json({ message: 'Removed' });
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
// @desc Hours served per person (checked-in shifts), over the events the user can see
|
||||
// @route GET /api/volunteers/manage/hours?eventId=&from=&to=
|
||||
const hours = async (req, res) => {
|
||||
try {
|
||||
const scope = await listWhere(req);
|
||||
const eventWhere = withScope(req.query.eventId ? { id: String(req.query.eventId) } : {}, scope);
|
||||
const rows = await v.hoursServed({ eventWhere, from: req.query.from || null, to: req.query.to || null });
|
||||
res.json(rows);
|
||||
} catch (error) {
|
||||
fail(res, error);
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = {
|
||||
getMine, getEventRoles, signUp, withdraw, requestSwap, cancelSwap, acceptSwap, checkIn,
|
||||
listEvents, getRoster, getQr, checkInManual,
|
||||
getSettings, saveSettings, createRole, updateRole, deleteRole, assign, remove, hours,
|
||||
};
|
||||
@@ -26,6 +26,10 @@ const BLOCKED = [
|
||||
['POST', /^\/api\/waitlist\/?$/],
|
||||
['POST', /^\/api\/coupons\/?$/],
|
||||
['POST', /^\/api\/bundles\/event\/[^/]+\/?$/],
|
||||
// Volunteer rosters: new roles and new people on them (they can carry a free ticket).
|
||||
['POST', /^\/api\/volunteers\/roles\/[^/]+\/sign-up\/?$/],
|
||||
['POST', /^\/api\/volunteers\/manage\/events\/[^/]+\/roles\/?$/],
|
||||
['POST', /^\/api\/volunteers\/manage\/roles\/[^/]+\/assign\/?$/],
|
||||
];
|
||||
|
||||
function isBlocked(method, path) {
|
||||
|
||||
@@ -184,6 +184,7 @@ app.get('/health', async (req, res) => {
|
||||
app.use('/api/hub', require('./routes/hubRoutes'));
|
||||
app.use('/api/campuses', require('./routes/campusRoutes'));
|
||||
app.use('/api/kids', require('./routes/kidsRoutes'));
|
||||
app.use('/api/volunteers', require('./routes/volunteerRoutes'));
|
||||
app.use('/api/users', userRoutes);
|
||||
app.use('/api/events', eventRoutes);
|
||||
app.use('/api/registrations', registrationRoutes);
|
||||
@@ -985,6 +986,32 @@ app.get('/docs', async (req, res) => {
|
||||
{ method:'POST', path:'/api/kids/events/:eventId/sync', auth:'staff+', desc:'Sync an offline desk\'s check-ins and check-outs (idempotent by clientId). Audited as kids_offline_sync' },
|
||||
]},
|
||||
|
||||
{ title: 'Volunteer rosters', base: '/api/volunteers', endpoints: [
|
||||
{ method:'GET', path:'/api/volunteers/me', auth:'user', desc:'My shifts (upcoming and the last week), cover requests I could take, and events looking for volunteers' },
|
||||
{ method:'GET', path:'/api/volunteers/events/:eventId', auth:'user', desc:'An event\'s serving roles: shift, how many are needed and signed up, whether I\'m in it, open cover requests' },
|
||||
{ method:'POST', path:'/api/volunteers/roles/:id/sign-up', auth:'user', desc:'Sign up for a role. 409 ROLE_FULL when it\'s full, 409 SHIFT_CLASH when I serve elsewhere at the same time. Gives a free volunteer place when the event has one',
|
||||
responses:[{ status:201, desc:'Signed up', body:{ slotId:'s_1', ticket:true } }] },
|
||||
{ method:'DELETE', path:'/api/volunteers/slots/:id', auth:'user', desc:'Withdraw from a shift (not after checking in or once it\'s over). The event\'s notify recipients are emailed' },
|
||||
{ method:'POST', path:'/api/volunteers/slots/:id/swap', auth:'user', desc:'"Can\'t make it": ask for cover. The event\'s other volunteers are told; the request shows on everyone\'s Serving page', request:{ body:{ note:'Away that weekend' } } },
|
||||
{ method:'DELETE', path:'/api/volunteers/swaps/:id', auth:'user', desc:'Cancel my cover request' },
|
||||
{ method:'POST', path:'/api/volunteers/swaps/:id/accept', auth:'user', desc:'Take over someone\'s place. Happens at once (409 SWAP_CLOSED if someone was first); both volunteers and the event\'s notify recipients are told' },
|
||||
{ method:'POST', path:'/api/volunteers/check-in', auth:'user', desc:'Check in by scanning the event\'s volunteer QR code: every shift of mine on today is checked in; kids-room roles put me on duty in that room',
|
||||
request:{ body:{ qr:'SERVE-3f2a…' } }, responses:[{ status:200, desc:'Checked in', body:{ event:{ id:'e_1', title:'Sunday service' }, checkedIn:[{ role:'Kids', kidsRoom:'Toddlers' }], already:[] } }] },
|
||||
{ method:'GET', path:'/api/volunteers/manage/events', auth:'staff+', desc:'Events with serving roles from the last 30 days on (?all=1, supervisors: every upcoming event). Campus-scoped' },
|
||||
{ method:'GET', path:'/api/volunteers/manage/events/:eventId', auth:'staff+', desc:'The roster sheet: roles with volunteers, contact details, check-ins and fill rate. ?log=1 writes the access log' },
|
||||
{ method:'GET', path:'/api/volunteers/manage/events/:eventId/qr', auth:'staff+', desc:'The volunteer check-in QR code value for the event (made the first time)' },
|
||||
{ method:'POST', path:'/api/volunteers/manage/slots/:id/check-in', auth:'staff+', desc:'Check a volunteer in by hand (undo:true to undo). Audited as volunteer_checked_in_manual' },
|
||||
{ method:'GET', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'The volunteer ticket setting, the main tickets that can be it and the event\'s kids rooms' },
|
||||
{ method:'PUT', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'Free volunteer place: optionId of a main ticket, "new" for a free "Volunteer" ticket, null for off (the default). Audited as volunteer_settings_updated', request:{ body:{ optionId:'new' } } },
|
||||
{ method:'POST', path:'/api/volunteers/manage/events/:eventId/roles', auth:'supervisor+', desc:'Add a serving role (sessionId required on multi-session events; shift times optional). Audited as volunteer_roles_changed',
|
||||
request:{ body:{ name:'Welcome', needed:4, sessionId:null, startsAt:'2026-11-08T07:30:00.000Z', endsAt:'2026-11-08T09:30:00.000Z', description:'Front doors', kidsRoomId:null } } },
|
||||
{ method:'PUT', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Change a role' },
|
||||
{ method:'DELETE', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Delete a role (refused once someone checked in for it); its volunteers are told' },
|
||||
{ method:'POST', path:'/api/volunteers/manage/roles/:id/assign', auth:'supervisor+', desc:'Put someone on a role (allowed beyond the number needed); they\'re told. Audited as volunteer_assigned', request:{ body:{ userId:'u_1' } } },
|
||||
{ method:'DELETE', path:'/api/volunteers/manage/slots/:id', auth:'supervisor+', desc:'Take someone off a role (not after check-in); they\'re told. Audited as volunteer_removed' },
|
||||
{ method:'GET', path:'/api/volunteers/manage/hours?eventId=&from=&to=', auth:'supervisor+', desc:'Hours served per person (checked-in shifts × shift length), most first. Campus-scoped' },
|
||||
]},
|
||||
|
||||
{ title: 'Privacy (POPIA)', base: '/api/privacy', endpoints: [
|
||||
{ method:'GET', path:'/api/privacy/me', auth:'user', desc:'My news opt-in, its history, and my privacy requests',
|
||||
responses:[{ status:200, desc:'Success', body:{ news:{ email:true, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z', canWhatsApp:false, notificationPreference:'email', history:[{ channel:'email', granted:true, source:'signup', createdAt:'2026-10-23T08:00:00.000Z' }], requests:[] }}]},
|
||||
|
||||
@@ -45,6 +45,10 @@ const JOBS = [
|
||||
return { reminders, certificates };
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'volunteers', label: 'Volunteer reminders the day before a shift', cron: '*/15 * * * *', env: 'VOLUNTEER_JOBS_ENABLED',
|
||||
run: () => require('../utils/volunteers').runReminderJob(),
|
||||
},
|
||||
{
|
||||
name: 'consent', label: 'Parental consent reminders and medical-detail deletion', cron: '0 9 * * *', env: 'CONSENT_JOBS_ENABLED',
|
||||
run: async () => {
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
const express = require('express');
|
||||
const router = express.Router();
|
||||
const c = require('../controllers/volunteerController');
|
||||
const { protect, staff, supervisor } = require('../middleware/authMiddleware');
|
||||
const { scopeEvent, scopeList } = require('../utils/campusScope');
|
||||
|
||||
// My account → Serving (anyone with an account can volunteer; only their own slots)
|
||||
router.get('/me', protect, c.getMine);
|
||||
router.get('/events/:eventId', protect, c.getEventRoles);
|
||||
router.post('/roles/:id/sign-up', protect, c.signUp);
|
||||
router.delete('/slots/:id', protect, c.withdraw);
|
||||
router.post('/slots/:id/swap', protect, c.requestSwap);
|
||||
router.delete('/swaps/:id', protect, c.cancelSwap);
|
||||
router.post('/swaps/:id/accept', protect, c.acceptSwap);
|
||||
router.post('/check-in', protect, c.checkIn);
|
||||
|
||||
// The roster on the day (staff)
|
||||
router.get('/manage/events', protect, staff, scopeList, c.listEvents);
|
||||
router.get('/manage/events/:eventId', protect, staff, scopeEvent(), c.getRoster);
|
||||
router.get('/manage/events/:eventId/qr', protect, staff, scopeEvent(), c.getQr);
|
||||
router.post('/manage/slots/:id/check-in', protect, staff, scopeEvent({ resolve: 'volunteerSlot' }), c.checkInManual);
|
||||
|
||||
// Roles, people, settings and reports (supervisors)
|
||||
router.get('/manage/events/:eventId/settings', protect, supervisor, scopeEvent(), c.getSettings);
|
||||
router.put('/manage/events/:eventId/settings', protect, supervisor, scopeEvent({ need: 'manage' }), c.saveSettings);
|
||||
router.post('/manage/events/:eventId/roles', protect, supervisor, scopeEvent({ need: 'manage' }), c.createRole);
|
||||
router.put('/manage/roles/:id', protect, supervisor, scopeEvent({ resolve: 'servingRole', need: 'manage' }), c.updateRole);
|
||||
router.delete('/manage/roles/:id', protect, supervisor, scopeEvent({ resolve: 'servingRole', need: 'manage' }), c.deleteRole);
|
||||
router.post('/manage/roles/:id/assign', protect, supervisor, scopeEvent({ resolve: 'servingRole' }), c.assign);
|
||||
router.delete('/manage/slots/:id', protect, supervisor, scopeEvent({ resolve: 'volunteerSlot' }), c.remove);
|
||||
router.get('/manage/hours', protect, supervisor, scopeList, c.hours);
|
||||
|
||||
module.exports = router;
|
||||
@@ -17,6 +17,7 @@ const ACCESS_ACTIONS = {
|
||||
impersonation: 'Viewed the site as another user',
|
||||
kids_rooms: 'Kids check-in desk or room opened',
|
||||
kids_offline: 'Kids check-in list downloaded for offline use',
|
||||
volunteer_roster: 'Volunteer roster opened',
|
||||
};
|
||||
|
||||
/**
|
||||
|
||||
@@ -104,6 +104,8 @@ const RESOLVERS = {
|
||||
},
|
||||
kidsCheckIn: async id => shape((await prisma.kidsCheckIn.findUnique({ where: { id }, select: { event: EV } }))?.event),
|
||||
kidsAlert: async id => shape((await prisma.kidsAlert.findUnique({ where: { id }, select: { event: EV } }))?.event),
|
||||
servingRole: async id => shape((await prisma.servingRole.findUnique({ where: { id }, select: { event: EV } }))?.event),
|
||||
volunteerSlot: async id => shape((await prisma.volunteerSlot.findUnique({ where: { id }, select: { role: { select: { event: EV } } } }))?.role?.event),
|
||||
};
|
||||
|
||||
/** The event a record belongs to (see RESOLVERS), or null. */
|
||||
|
||||
@@ -584,7 +584,7 @@ async function pageParent({ checkInId, message, staffUserId }, db = prisma) {
|
||||
async function board({ eventId, sessionId = null, now = new Date() }, db = prisma) {
|
||||
const event = await loadKidsEvent(eventId, db);
|
||||
const { occasion, sessionId: sid } = occasionFor(event, event.sessions, sessionId, now);
|
||||
const [rooms, checkIns, duties, alerts] = await Promise.all([
|
||||
const [rooms, checkIns, duties, alerts, rostered] = await Promise.all([
|
||||
roomsFor(event, db),
|
||||
db.kidsCheckIn.findMany({
|
||||
where: { eventId: event.id, occasion },
|
||||
@@ -598,6 +598,9 @@ async function board({ eventId, sessionId = null, now = new Date() }, db = prism
|
||||
}),
|
||||
db.kidsRoomDuty.findMany({ where: { occasion, endedAt: null, room: { setId: event.kidsRoomSetId } }, include: { user: { select: { id: true, name: true } } } }),
|
||||
db.kidsAlert.findMany({ where: { eventId: event.id, occasion }, orderBy: { createdAt: 'desc' }, take: 50, include: { createdBy: { select: { name: true } } } }),
|
||||
// Volunteer rosters (1.46.0): who is rostered in each room. They count as leaders on duty
|
||||
// once they check in (a KidsRoomDuty with fromRoster), like "I'm on duty".
|
||||
require('./volunteers').rosteredForRooms(event, occasion, db),
|
||||
]);
|
||||
const familyIds = [...new Set(checkIns.map(c => c.pickupCode.familyId).filter(Boolean))];
|
||||
const families = familyIds.length ? await db.family.findMany({ where: { id: { in: familyIds } }, include: FAMILY_INCLUDE }) : [];
|
||||
@@ -614,7 +617,7 @@ async function board({ eventId, sessionId = null, now = new Date() }, db = prism
|
||||
sessionLabel,
|
||||
rooms: rooms.map(r => {
|
||||
const leaders = duties.filter(d => d.roomId === r.id).map(d => d.user);
|
||||
return { id: r.id, name: r.name, minAge: r.minAge, maxAge: r.maxAge, capacity: r.capacity, ratio: r.ratio, order: r.order, leaderNames: leaders.map(l => l.name), leaderIds: leaders.map(l => l.id), ...roomStatus(r, inByRoom[r.id] || 0, leaders.length) };
|
||||
return { id: r.id, name: r.name, minAge: r.minAge, maxAge: r.maxAge, capacity: r.capacity, ratio: r.ratio, order: r.order, leaderNames: leaders.map(l => l.name), leaderIds: leaders.map(l => l.id), rostered: rostered[r.id] || [], ...roomStatus(r, inByRoom[r.id] || 0, leaders.length) };
|
||||
}),
|
||||
checkIns: checkIns.map(c => {
|
||||
const fam = famById[c.pickupCode.familyId];
|
||||
@@ -835,7 +838,7 @@ module.exports = {
|
||||
randomCode, normaliseCode, ageOn, fitsRoom, suggestRoom, roomStatus, stickerAlert, occasionFor, checkInMessage, listNames,
|
||||
childView, familyView, loadFamily, familyOfUser, createFamily, cleanChild, cleanAdult, custodyChanged, searchFamilies,
|
||||
loadKidsEvent, roomsFor, getSettings, saveSettings,
|
||||
codeForFamily, reserveCodes, checkIn, checkOut, overrideCheckOut, sendCheckInMessages, pageParent,
|
||||
codeForFamily, reserveCodes, checkIn, checkOut, overrideCheckOut, messageParent, sendCheckInMessages, pageParent,
|
||||
board, setDuty, moveRoom, activeForFamily, offlineSnapshot, syncOffline,
|
||||
removeFromFamily, exportFamily, runKidsRetention, previewKidsRetention,
|
||||
};
|
||||
|
||||
@@ -1513,6 +1513,7 @@ async function sendAttendeeFormLinkMessage(attendee) {
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
getEventNotifyEmails,
|
||||
buildEventNotifyRecipientList,
|
||||
sendAttendeeFormLinkMessage,
|
||||
sendRegistrationEmails,
|
||||
|
||||
@@ -460,7 +460,10 @@ async function anonymiseUser(userId, db = prisma) {
|
||||
const { familyDeleted } = await require('./kids').removeFromFamily(tx, userId);
|
||||
await tx.kidsCheckIn.updateMany({ where: { checkedOutById: userId }, data: { checkedOutById: null } });
|
||||
|
||||
return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted };
|
||||
// Volunteer rosters: shifts still to come are given up; past ones stay for hours served.
|
||||
const shiftsGivenUp = await require('./volunteers').forgetVolunteer(tx, userId);
|
||||
|
||||
return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted, shiftsGivenUp };
|
||||
});
|
||||
|
||||
await clearTrustedDevices(userId);
|
||||
@@ -482,7 +485,7 @@ async function exportUserData(userId, db = prisma) {
|
||||
});
|
||||
if (!user) return null;
|
||||
|
||||
const [registrations, payments, tickets, waitlist, certificates, feedback, consents, security, requests, notices, family] = await Promise.all([
|
||||
const [registrations, payments, tickets, waitlist, certificates, feedback, consents, security, requests, notices, family, volunteering] = await Promise.all([
|
||||
db.registration.findMany({
|
||||
where: { userId },
|
||||
orderBy: { createdAt: 'asc' },
|
||||
@@ -507,6 +510,7 @@ async function exportUserData(userId, db = prisma) {
|
||||
db.dataRequest.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, select: { type: true, status: true, details: true, response: true, createdAt: true, closedAt: true } }),
|
||||
db.noticeAcceptance.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, select: { version: true, source: true, createdAt: true } }),
|
||||
require('./kids').exportFamily(userId, db),
|
||||
require('./volunteers').exportVolunteering(userId, db),
|
||||
]);
|
||||
|
||||
return {
|
||||
@@ -549,6 +553,7 @@ async function exportUserData(userId, db = prisma) {
|
||||
accountActivity: security.map(s => ({ type: s.type, ip: s.ip, device: s.device, at: s.createdAt })),
|
||||
dataRequests: requests,
|
||||
kidsFamily: family,
|
||||
volunteering,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -605,6 +610,10 @@ async function dataExportPdf(data) {
|
||||
heading('Certificates');
|
||||
for (const c of data.certificates) para(`${c.event} — ${c.code}${c.revoked ? ' (withdrawn)' : ''}`);
|
||||
}
|
||||
if (data.volunteering?.length) {
|
||||
heading('Serving (volunteer rosters)');
|
||||
for (const s of data.volunteering) para(`${fmt(s.from)} — ${s.role}, ${s.event}${s.checkedIn ? ' (checked in)' : ''}`);
|
||||
}
|
||||
if (data.feedback.length) {
|
||||
heading('Feedback you gave');
|
||||
for (const f of data.feedback) {
|
||||
|
||||
@@ -0,0 +1,782 @@
|
||||
/**
|
||||
* Volunteer rosters (1.46.0). Who serves where at an event:
|
||||
*
|
||||
* - Serving roles (Welcome, Parking, Kids, Sound…) belong to one event, or — on a multi-session
|
||||
* event — to one session, with the number of people needed and optional shift times (default:
|
||||
* the session's or event's times). Rosters never repeat: each event/session has its own roles.
|
||||
* - Anyone with an account can sign up for a role that isn't full; supervisors can also assign
|
||||
* people (even beyond the number needed). Nobody can be in two roles whose shifts overlap.
|
||||
* - Volunteers get a reminder the day before their shift. "Can't make it" asks for cover: the
|
||||
* request shows on the Serving page and goes to the event's other volunteers, and the place
|
||||
* moves as soon as someone accepts — the event's notify recipients are told, nobody approves.
|
||||
* - On the day volunteers check themselves in by scanning the event's volunteer QR code (or staff
|
||||
* tick them in). A role linked to a kids room puts its volunteers on duty in that room when they
|
||||
* check in, so they count for the room's leader-to-children ratio.
|
||||
* - A free volunteer place on a ticket of the event is off by default; a supervisor turns it on
|
||||
* per event by choosing the ticket. Volunteers who already have a ticket keep theirs.
|
||||
*/
|
||||
|
||||
const crypto = require('crypto');
|
||||
const { v4: uuidv4 } = require('uuid');
|
||||
const prisma = require('../config/db');
|
||||
const sessionsUtil = require('./sessions');
|
||||
|
||||
const MAX_NEEDED = 200;
|
||||
const MAX_ROLES = 100;
|
||||
const HOUR = 60 * 60 * 1000;
|
||||
// Reminders go out this long before a shift, to people who signed up before then.
|
||||
const REMIND_BEFORE_MS = 24 * HOUR;
|
||||
// What the check-in QR code holds: the prefix, then the event's token.
|
||||
const QR_PREFIX = 'SERVE-';
|
||||
|
||||
function volunteerError(message, statusCode = 400, code = undefined) {
|
||||
return Object.assign(new Error(message), { statusCode, ...(code ? { code } : {}) });
|
||||
}
|
||||
|
||||
// ─── Pure helpers ─────────────────────────────────────────────────────────────
|
||||
|
||||
/** A role's shift: its own times, else its session's, else the event's. */
|
||||
function shiftOf(role, event) {
|
||||
const session = role.session || (role.sessionId ? (event.sessions || []).find(s => s.id === role.sessionId) : null);
|
||||
return {
|
||||
startsAt: new Date(role.startsAt || session?.startsAt || event.startDate),
|
||||
endsAt: new Date(role.endsAt || session?.endsAt || event.endDate),
|
||||
};
|
||||
}
|
||||
|
||||
/** Whether two shifts overlap (touching ends don't count: 08:00–10:00 and 10:00–12:00 are fine). */
|
||||
function overlaps(a, b) {
|
||||
return new Date(a.startsAt) < new Date(b.endsAt) && new Date(b.startsAt) < new Date(a.endsAt);
|
||||
}
|
||||
|
||||
/** Hours in a shift, to the nearest quarter hour. */
|
||||
function shiftHours(shift) {
|
||||
const h = (new Date(shift.endsAt) - new Date(shift.startsAt)) / HOUR;
|
||||
return h > 0 ? Math.round(h * 4) / 4 : 0;
|
||||
}
|
||||
|
||||
/** { needed, filled, open, full } for a role with `filled` volunteers. */
|
||||
function fillOf(needed, filled) {
|
||||
return { needed, filled, open: Math.max(0, needed - filled), full: filled >= needed };
|
||||
}
|
||||
|
||||
/** Volunteers can check in on the day(s) of their shift, until it ends. */
|
||||
function checkInOpen(shift, now = new Date()) {
|
||||
const today = sessionsUtil.dayKey(now);
|
||||
return today >= sessionsUtil.dayKey(shift.startsAt) && today <= sessionsUtil.dayKey(shift.endsAt) && new Date(now) <= new Date(shift.endsAt);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a slot's reminder is due: not sent yet, the shift starts within the next 24 hours, and
|
||||
* the person signed up more than half an hour ago (someone who just signed up doesn't need one).
|
||||
*/
|
||||
function reminderDue({ remindedAt, createdAt }, shift, now = new Date()) {
|
||||
if (remindedAt) return false;
|
||||
const t = new Date(now).getTime();
|
||||
const start = new Date(shift.startsAt).getTime();
|
||||
return start > t && start - t <= REMIND_BEFORE_MS && t - new Date(createdAt).getTime() > HOUR / 2;
|
||||
}
|
||||
|
||||
/** The kids room occasion a check-in counts for (see utils/kids.js occasionFor): the session, or today. */
|
||||
function kidsOccasion(role, now = new Date()) {
|
||||
return role.sessionId || sessionsUtil.dayKey(now);
|
||||
}
|
||||
|
||||
/** Ticket options only staff hand out — the kids check-in and volunteer tickets — never sold publicly. */
|
||||
function reservedOptionIds(event) {
|
||||
return [event?.kidsOptionId, event?.volunteerOptionId].filter(Boolean);
|
||||
}
|
||||
|
||||
/** The event's options without the reserved ones (for public event pages and lists). */
|
||||
function publicOptions(event) {
|
||||
const reserved = new Set(reservedOptionIds(event));
|
||||
return (event?.eventOptions || []).filter(o => !reserved.has(o.id));
|
||||
}
|
||||
|
||||
function fmtWhen(d) {
|
||||
return new Date(d).toLocaleString('en-GB', { timeZone: sessionsUtil.TIMEZONE, weekday: 'short', day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' });
|
||||
}
|
||||
|
||||
function fmtTime(d) {
|
||||
return new Date(d).toLocaleTimeString('en-GB', { timeZone: sessionsUtil.TIMEZONE, hour: '2-digit', minute: '2-digit' });
|
||||
}
|
||||
|
||||
/** "Sat 7 Nov, 08:00–10:30" (the end date is added when the shift runs past midnight). */
|
||||
function shiftText(shift) {
|
||||
const sameDay = sessionsUtil.dayKey(shift.startsAt) === sessionsUtil.dayKey(shift.endsAt);
|
||||
return `${fmtWhen(shift.startsAt)}–${sameDay ? fmtTime(shift.endsAt) : fmtWhen(shift.endsAt)}`;
|
||||
}
|
||||
|
||||
function cleanText(v, max) {
|
||||
return String(v ?? '').trim().slice(0, max);
|
||||
}
|
||||
|
||||
// ─── Loading ──────────────────────────────────────────────────────────────────
|
||||
|
||||
const EVENT_SELECT = {
|
||||
id: true, title: true, startDate: true, endDate: true, scheduleType: true, isActive: true, location: true, campusId: true,
|
||||
kidsCheckIn: true, kidsRoomSetId: true, kidsOptionId: true, volunteerOptionId: true, volunteerCheckInToken: true,
|
||||
sessions: { orderBy: { startsAt: 'asc' } },
|
||||
};
|
||||
|
||||
async function loadEvent(eventId, db = prisma) {
|
||||
const event = await db.event.findUnique({ where: { id: String(eventId || '') }, select: EVENT_SELECT });
|
||||
if (!event) throw volunteerError('Event not found', 404);
|
||||
return event;
|
||||
}
|
||||
|
||||
const USER_SELECT = { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true };
|
||||
|
||||
const ROLE_INCLUDE = {
|
||||
session: true,
|
||||
kidsRoom: { select: { id: true, name: true } },
|
||||
slots: {
|
||||
orderBy: { createdAt: 'asc' },
|
||||
include: { user: { select: USER_SELECT }, assignedBy: { select: { name: true } }, checkedInBy: { select: { name: true } } },
|
||||
},
|
||||
swaps: { where: { status: 'open' }, orderBy: { createdAt: 'asc' } },
|
||||
};
|
||||
|
||||
const realEmail = e => (e && !/@(guest\.local|deleted\.invalid|deleted\.local)$/.test(e) ? e : null);
|
||||
|
||||
/**
|
||||
* A role for the API. `staff` adds the volunteers (names, contact, check-ins); others see only
|
||||
* how full it is, whether they're in it, and open cover requests.
|
||||
*/
|
||||
function roleView(role, event, { staff = false, userId = null, now = new Date() } = {}) {
|
||||
const shift = shiftOf(role, event);
|
||||
const sessions = sessionsUtil.activeSessions(event.sessions);
|
||||
const mine = userId ? role.slots.find(s => s.userId === userId) : null;
|
||||
const swapBySlot = Object.fromEntries(role.swaps.map(w => [w.slotId, w]));
|
||||
return {
|
||||
id: role.id,
|
||||
eventId: role.eventId,
|
||||
sessionId: role.sessionId,
|
||||
sessionLabel: role.session ? sessionsUtil.sessionLabel(role.session, sessions) : null,
|
||||
name: role.name,
|
||||
description: role.description || '',
|
||||
startsAt: role.startsAt,
|
||||
endsAt: role.endsAt,
|
||||
shift: { startsAt: shift.startsAt, endsAt: shift.endsAt, text: shiftText(shift), hours: shiftHours(shift) },
|
||||
kidsRoom: role.kidsRoom || null,
|
||||
order: role.order,
|
||||
past: new Date(shift.endsAt) < new Date(now),
|
||||
...fillOf(role.needed, role.slots.length),
|
||||
mine: mine ? { slotId: mine.id, checkedInAt: mine.checkedInAt, swapId: swapBySlot[mine.id]?.id || null } : null,
|
||||
coverNeeded: role.swaps.filter(w => w.fromUserId !== userId).map(w => ({ swapId: w.id, note: w.note || '' })),
|
||||
...(staff ? {
|
||||
volunteers: role.slots.map(s => ({
|
||||
slotId: s.id,
|
||||
userId: s.user.id,
|
||||
name: s.user.name,
|
||||
phone: s.user.phoneNumber || null,
|
||||
email: realEmail(s.user.email),
|
||||
assignedBy: s.assignedBy?.name || null,
|
||||
checkedInAt: s.checkedInAt,
|
||||
checkedInBy: s.checkedInBy?.name || null,
|
||||
checkInMethod: s.checkInMethod,
|
||||
swapOpen: !!swapBySlot[s.id],
|
||||
hasTicket: !!s.registrationId,
|
||||
})),
|
||||
} : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** An event's roster: its roles in order (by session, then shift start, then order). */
|
||||
async function roster(eventId, { staff = false, userId = null, now = new Date() } = {}, db = prisma) {
|
||||
const event = await loadEvent(eventId, db);
|
||||
const roles = await db.servingRole.findMany({ where: { eventId: event.id }, include: ROLE_INCLUDE });
|
||||
const views = roles.map(r => roleView(r, event, { staff, userId, now }))
|
||||
.sort((a, b) => new Date(a.shift.startsAt) - new Date(b.shift.startsAt) || a.order - b.order || a.name.localeCompare(b.name));
|
||||
const totals = views.reduce((t, r) => ({ needed: t.needed + r.needed, filled: t.filled + Math.min(r.filled, r.needed), checkedIn: t.checkedIn + (r.volunteers || []).filter(v => v.checkedInAt).length }), { needed: 0, filled: 0, checkedIn: 0 });
|
||||
return {
|
||||
event: { id: event.id, title: event.title, startDate: event.startDate, endDate: event.endDate, scheduleType: event.scheduleType, location: event.location, kidsCheckIn: event.kidsCheckIn },
|
||||
sessions: sessionsUtil.activeSessions(event.sessions).map(s => ({ id: s.id, label: sessionsUtil.sessionLabel(s, event.sessions), startsAt: s.startsAt, endsAt: s.endsAt })),
|
||||
roles: views,
|
||||
totals: { ...totals, fillRate: totals.needed ? Math.round((totals.filled / totals.needed) * 100) : null },
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Roles (supervisors) ──────────────────────────────────────────────────────
|
||||
|
||||
function parseTime(v, what) {
|
||||
if (v === undefined) return undefined;
|
||||
if (v === null || v === '') return null;
|
||||
const d = new Date(v);
|
||||
if (Number.isNaN(d.getTime())) throw volunteerError(`Enter a valid ${what}.`);
|
||||
return d;
|
||||
}
|
||||
|
||||
/** Check and clean a role from the request (`existing` when changing one). */
|
||||
async function cleanRole(event, input, existing = null, db = prisma) {
|
||||
const b = input || {};
|
||||
const data = {};
|
||||
if (b.name !== undefined || !existing) {
|
||||
data.name = cleanText(b.name, 60);
|
||||
if (!data.name) throw volunteerError('Enter a name for the role (e.g. Welcome, Parking, Sound).');
|
||||
}
|
||||
if (b.description !== undefined) data.description = cleanText(b.description, 500) || null;
|
||||
if (b.needed !== undefined || !existing) {
|
||||
const n = parseInt(b.needed ?? 1, 10);
|
||||
if (!Number.isFinite(n) || n < 1 || n > MAX_NEEDED) throw volunteerError(`The number of people needed must be from 1 to ${MAX_NEEDED}.`);
|
||||
data.needed = n;
|
||||
}
|
||||
if (b.sessionId !== undefined || !existing) {
|
||||
if (event.scheduleType === 'sessions') {
|
||||
const session = event.sessions.find(s => s.id === b.sessionId && !s.cancelledAt);
|
||||
if (!session) throw volunteerError('Choose the session this role is for.');
|
||||
data.sessionId = session.id;
|
||||
} else data.sessionId = null;
|
||||
}
|
||||
const startsAt = parseTime(b.startsAt, 'start time');
|
||||
const endsAt = parseTime(b.endsAt, 'end time');
|
||||
if (startsAt !== undefined) data.startsAt = startsAt;
|
||||
if (endsAt !== undefined) data.endsAt = endsAt;
|
||||
const shift = shiftOf({ ...existing, ...data, session: undefined }, event);
|
||||
if (shift.endsAt <= shift.startsAt) throw volunteerError('The shift has to end after it starts.');
|
||||
if (b.kidsRoomId !== undefined) {
|
||||
if (!b.kidsRoomId) data.kidsRoomId = null;
|
||||
else {
|
||||
const room = event.kidsRoomSetId ? await db.allocationGroup.findFirst({ where: { id: String(b.kidsRoomId), setId: event.kidsRoomSetId } }) : null;
|
||||
if (!room) throw volunteerError('Choose one of this event\'s kids rooms (set up under Kids check-in setup).');
|
||||
data.kidsRoomId = room.id;
|
||||
}
|
||||
}
|
||||
if (b.order !== undefined) data.order = Math.max(0, Math.min(1000, parseInt(b.order, 10) || 0));
|
||||
return data;
|
||||
}
|
||||
|
||||
async function createRole(eventId, input, db = prisma) {
|
||||
const event = await loadEvent(eventId, db);
|
||||
if (await db.servingRole.count({ where: { eventId: event.id } }) >= MAX_ROLES) throw volunteerError(`An event can have up to ${MAX_ROLES} serving roles.`);
|
||||
const data = await cleanRole(event, input, null, db);
|
||||
if (input?.order === undefined) data.order = await db.servingRole.count({ where: { eventId: event.id, sessionId: data.sessionId } });
|
||||
return db.servingRole.create({ data: { ...data, eventId: event.id } });
|
||||
}
|
||||
|
||||
async function updateRole(roleId, input, db = prisma) {
|
||||
const existing = await db.servingRole.findUnique({ where: { id: String(roleId || '') } });
|
||||
if (!existing) throw volunteerError('Role not found', 404);
|
||||
const event = await loadEvent(existing.eventId, db);
|
||||
const data = await cleanRole(event, input, existing, db);
|
||||
if (data.sessionId !== undefined && data.sessionId !== existing.sessionId && await db.volunteerSlot.count({ where: { roleId: existing.id } })) {
|
||||
throw volunteerError('People have signed up for this role, so it can\'t move to another session — add a new role there instead.');
|
||||
}
|
||||
return db.servingRole.update({ where: { id: existing.id }, data });
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete a role. Refused once someone has checked in for it (it counts for hours served).
|
||||
* Returns the volunteers who were on it, so they can be told.
|
||||
*/
|
||||
async function deleteRole(roleId, db = prisma) {
|
||||
const role = await db.servingRole.findUnique({ where: { id: String(roleId || '') }, include: { slots: { include: { user: { select: USER_SELECT } } } } });
|
||||
if (!role) throw volunteerError('Role not found', 404);
|
||||
if (role.slots.some(s => s.checkedInAt)) throw volunteerError('Someone has already checked in for this role, so it stays on the roster (it counts for hours served).');
|
||||
const event = await loadEvent(role.eventId, db);
|
||||
await db.$transaction(async tx => {
|
||||
for (const s of role.slots) await releasePlace(tx, s);
|
||||
await tx.servingRole.delete({ where: { id: role.id } });
|
||||
});
|
||||
return { role, event, volunteers: role.slots.map(s => s.user) };
|
||||
}
|
||||
|
||||
// ─── Settings ─────────────────────────────────────────────────────────────────
|
||||
|
||||
/** The event's volunteer settings and the tickets that can be the volunteer ticket. */
|
||||
async function getSettings(eventId, db = prisma) {
|
||||
const event = await loadEvent(eventId, db);
|
||||
const [options, rooms] = await Promise.all([
|
||||
db.eventOption.findMany({ where: { eventId: event.id, isMainTicket: true, sessionMode: 'all' }, select: { id: true, name: true, price: true }, orderBy: { name: 'asc' } }),
|
||||
event.kidsRoomSetId ? db.allocationGroup.findMany({ where: { setId: event.kidsRoomSetId }, select: { id: true, name: true }, orderBy: { order: 'asc' } }) : [],
|
||||
]);
|
||||
return {
|
||||
event: { id: event.id, title: event.title, volunteerOptionId: event.volunteerOptionId },
|
||||
options: options.filter(o => o.id !== event.kidsOptionId),
|
||||
kidsRooms: rooms,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Turn the free volunteer place on or off. `optionId: 'new'` adds a free "Volunteer" main ticket
|
||||
* (staff-only: it never shows publicly); null switches it off (places already given stay).
|
||||
*/
|
||||
async function saveSettings(eventId, { optionId }, db = prisma) {
|
||||
const event = await loadEvent(eventId, db);
|
||||
let next = null;
|
||||
if (optionId === 'new') {
|
||||
next = (await db.eventOption.create({ data: { eventId: event.id, name: 'Volunteer', price: 0, isMainTicket: true, sessionMode: 'all' } })).id;
|
||||
} else if (optionId) {
|
||||
const opt = await db.eventOption.findFirst({ where: { id: String(optionId), eventId: event.id, isMainTicket: true, sessionMode: 'all' } });
|
||||
if (!opt || opt.id === event.kidsOptionId) throw volunteerError('Choose a main ticket of this event that covers the whole event (not the kids ticket).');
|
||||
next = opt.id;
|
||||
}
|
||||
await db.event.update({ where: { id: event.id }, data: { volunteerOptionId: next } });
|
||||
return getSettings(event.id, db);
|
||||
}
|
||||
|
||||
/** The event's check-in QR value (the token is made the first time). */
|
||||
async function checkInQr(eventId, db = prisma) {
|
||||
const event = await loadEvent(eventId, db);
|
||||
let token = event.volunteerCheckInToken;
|
||||
if (!token) {
|
||||
token = crypto.randomBytes(12).toString('hex');
|
||||
await db.event.update({ where: { id: event.id }, data: { volunteerCheckInToken: token } });
|
||||
}
|
||||
return { token, qr: QR_PREFIX + token };
|
||||
}
|
||||
|
||||
// ─── The free volunteer place ─────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Give a volunteer a free place on the event's volunteer ticket, when that's switched on and they
|
||||
* have no ticket for the event yet. Returns the registration id (shared by their slots), or null.
|
||||
*/
|
||||
async function givePlace(tx, event, userId) {
|
||||
if (!event.volunteerOptionId) return null;
|
||||
const shared = await tx.volunteerSlot.findFirst({ where: { userId, registrationId: { not: null }, role: { eventId: event.id }, registration: { status: { not: 'cancelled' } } }, select: { registrationId: true } });
|
||||
if (shared) return shared.registrationId;
|
||||
const hasTicket = await tx.ticket.count({ where: { eventId: event.id, OR: [{ userId }, { holderUserId: userId }], registrationOption: { registration: { status: { not: 'cancelled' } } } } });
|
||||
if (hasTicket) return null;
|
||||
const registration = await tx.registration.create({ data: { userId, eventId: event.id, status: 'paid' } });
|
||||
const line = await tx.registrationOption.create({ data: { registrationId: registration.id, eventOptionId: event.volunteerOptionId, quantity: 1, priceSnapshot: 0 } });
|
||||
await tx.registrationOptionTranche.create({ data: { registrationOptionId: line.id, quantity: 1, priceSnapshot: 0 } });
|
||||
await tx.ticket.create({ data: { id: uuidv4(), qrCode: uuidv4(), registrationOptionId: line.id, userId, eventId: event.id, quantity: 1, emailSent: true } });
|
||||
return registration.id;
|
||||
}
|
||||
|
||||
/**
|
||||
* When a slot goes (withdrawn, removed, swapped away): cancel its free place if no other slot of
|
||||
* the person at the event still uses it and the ticket was never scanned.
|
||||
*/
|
||||
async function releasePlace(tx, slot) {
|
||||
if (!slot.registrationId) return;
|
||||
const others = await tx.volunteerSlot.count({ where: { registrationId: slot.registrationId, id: { not: slot.id }, userId: slot.userId } });
|
||||
if (others) return;
|
||||
const scanned = await tx.ticketUsage.count({ where: { ticket: { registrationOption: { registrationId: slot.registrationId } } } });
|
||||
if (scanned) return;
|
||||
await tx.registration.updateMany({ where: { id: slot.registrationId, status: { not: 'cancelled' } }, data: { status: 'cancelled' } });
|
||||
}
|
||||
|
||||
// ─── Signing up ───────────────────────────────────────────────────────────────
|
||||
|
||||
async function loadRole(roleId, db = prisma) {
|
||||
const role = await db.servingRole.findUnique({ where: { id: String(roleId || '') }, include: { session: true, slots: { select: { id: true, userId: true } } } });
|
||||
if (!role) throw volunteerError('Role not found', 404);
|
||||
return role;
|
||||
}
|
||||
|
||||
/** Refuse a role whose shift is over, a cancelled session, or an inactive event. */
|
||||
function assertOpen(role, event, now = new Date()) {
|
||||
if (!event.isActive) throw volunteerError('This event isn\'t open any more.');
|
||||
if (role.session?.cancelledAt) throw volunteerError('That session was cancelled.');
|
||||
if (shiftOf(role, event).endsAt <= new Date(now)) throw volunteerError('This shift is already over.');
|
||||
}
|
||||
|
||||
/** Refuse when the person serves in another role at the same time. */
|
||||
async function assertFree(tx, event, role, userId) {
|
||||
const shift = shiftOf(role, event);
|
||||
const theirs = await tx.volunteerSlot.findMany({ where: { userId, roleId: { not: role.id }, role: { eventId: event.id } }, include: { role: { include: { session: true } } } });
|
||||
const clash = theirs.find(s => overlaps(shiftOf(s.role, event), shift));
|
||||
if (clash) throw volunteerError(`${clash.role.name} (${shiftText(shiftOf(clash.role, event))}) is at the same time.`, 409, 'SHIFT_CLASH');
|
||||
}
|
||||
|
||||
/**
|
||||
* Put someone on a role: they signed up (`assignedById` null — refused when the role is full), or
|
||||
* a supervisor assigned them (allowed beyond the number needed).
|
||||
*/
|
||||
async function signUp({ roleId, userId, assignedById = null, now = new Date() }, db = prisma) {
|
||||
const role = await loadRole(roleId, db);
|
||||
const event = await loadEvent(role.eventId, db);
|
||||
assertOpen(role, event, now);
|
||||
if (role.slots.some(s => s.userId === userId)) throw volunteerError(assignedById ? 'This person is already on this role.' : 'You\'re already serving in this role.', 409);
|
||||
const slot = await db.$transaction(async tx => {
|
||||
if (!assignedById && await tx.volunteerSlot.count({ where: { roleId: role.id } }) >= role.needed) throw volunteerError('This role is full — thank you for offering!', 409, 'ROLE_FULL');
|
||||
await assertFree(tx, event, role, userId);
|
||||
const registrationId = await givePlace(tx, event, userId);
|
||||
return tx.volunteerSlot.create({ data: { roleId: role.id, userId, assignedById, registrationId } });
|
||||
});
|
||||
return { slot, role, event };
|
||||
}
|
||||
|
||||
async function loadSlot(slotId, db = prisma) {
|
||||
const slot = await db.volunteerSlot.findUnique({ where: { id: String(slotId || '') }, include: { user: { select: USER_SELECT }, role: { include: { session: true } } } });
|
||||
if (!slot) throw volunteerError('Not found', 404);
|
||||
return slot;
|
||||
}
|
||||
|
||||
/** Take someone off a role (they withdrew, or a supervisor removed them). Not after check-in. */
|
||||
async function leave({ slotId, userId = null }, db = prisma) {
|
||||
const slot = await loadSlot(slotId, db);
|
||||
if (userId && slot.userId !== userId) throw volunteerError('Not found', 404);
|
||||
if (slot.checkedInAt) throw volunteerError(`${userId ? 'You\'ve' : `${slot.user.name} has`} already checked in for this shift.`);
|
||||
const event = await loadEvent(slot.role.eventId, db);
|
||||
if (userId && shiftOf(slot.role, event).endsAt <= new Date()) throw volunteerError('This shift is already over.');
|
||||
await db.$transaction(async tx => {
|
||||
await tx.volunteerSwap.updateMany({ where: { slotId: slot.id, status: 'open' }, data: { status: 'cancelled', resolvedAt: new Date() } });
|
||||
await releasePlace(tx, slot);
|
||||
await tx.volunteerSlot.delete({ where: { id: slot.id } });
|
||||
});
|
||||
return { slot, event };
|
||||
}
|
||||
|
||||
// ─── Swaps ────────────────────────────────────────────────────────────────────
|
||||
|
||||
/** "Can't make it": ask for someone to take over the slot. One open request per slot. */
|
||||
async function requestSwap({ slotId, userId, note, now = new Date() }, db = prisma) {
|
||||
const slot = await loadSlot(slotId, db);
|
||||
if (slot.userId !== userId) throw volunteerError('Not found', 404);
|
||||
const event = await loadEvent(slot.role.eventId, db);
|
||||
assertOpen(slot.role, event, now);
|
||||
if (slot.checkedInAt) throw volunteerError('You\'ve already checked in for this shift.');
|
||||
const open = await db.volunteerSwap.findFirst({ where: { slotId: slot.id, status: 'open' } });
|
||||
if (open) return { swap: open, slot, event, created: false };
|
||||
const swap = await db.volunteerSwap.create({ data: { slotId: slot.id, roleId: slot.roleId, fromUserId: userId, note: cleanText(note, 300) || null } });
|
||||
return { swap, slot, event, created: true };
|
||||
}
|
||||
|
||||
async function cancelSwap({ swapId, userId }, db = prisma) {
|
||||
const out = await db.volunteerSwap.updateMany({ where: { id: String(swapId || ''), fromUserId: userId, status: 'open' }, data: { status: 'cancelled', resolvedAt: new Date() } });
|
||||
if (!out.count) throw volunteerError('Not found', 404);
|
||||
return { cancelled: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* Take over a slot someone can't make. Happens at once: the slot moves to the person accepting
|
||||
* (their reminder and free place are theirs now). Returns { swap, slot, from, to, event }.
|
||||
*/
|
||||
async function acceptSwap({ swapId, userId, now = new Date() }, db = prisma) {
|
||||
const swap = await db.volunteerSwap.findUnique({ where: { id: String(swapId || '') } });
|
||||
if (!swap || swap.status !== 'open' || !swap.slotId) throw volunteerError('Someone has already taken this place, or it isn\'t needed any more.', 409, 'SWAP_CLOSED');
|
||||
if (swap.fromUserId === userId) throw volunteerError('This is your own request — cancel it instead.');
|
||||
const slot = await loadSlot(swap.slotId, db);
|
||||
const event = await loadEvent(slot.role.eventId, db);
|
||||
assertOpen(slot.role, event, now);
|
||||
await db.$transaction(async tx => {
|
||||
// Claim the request first, so two people accepting at once can't both take it.
|
||||
const claimed = await tx.volunteerSwap.updateMany({ where: { id: swap.id, status: 'open' }, data: { status: 'accepted', toUserId: userId, resolvedAt: new Date(now) } });
|
||||
if (!claimed.count) throw volunteerError('Someone has just taken this place.', 409, 'SWAP_CLOSED');
|
||||
if (await tx.volunteerSlot.count({ where: { roleId: slot.roleId, userId } })) throw volunteerError('You\'re already serving in this role.', 409);
|
||||
await assertFree(tx, event, slot.role, userId);
|
||||
await releasePlace(tx, slot);
|
||||
const registrationId = await givePlace(tx, event, userId);
|
||||
await tx.volunteerSlot.update({ where: { id: slot.id }, data: { userId, assignedById: null, registrationId, remindedAt: null } });
|
||||
});
|
||||
const to = await db.user.findUnique({ where: { id: userId }, select: USER_SELECT });
|
||||
return { swap, slot, from: slot.user, to, event };
|
||||
}
|
||||
|
||||
/** Open cover requests the person could take (not their own, not a role they're in, not over). */
|
||||
async function openSwaps({ userId, now = new Date() }, db = prisma) {
|
||||
const swaps = await db.volunteerSwap.findMany({
|
||||
where: { status: 'open', fromUserId: { not: userId }, role: { event: { isActive: true, endDate: { gte: now } }, slots: { none: { userId } } } },
|
||||
include: { role: { include: { session: true, event: { select: EVENT_SELECT } } }, fromUser: { select: { name: true } } },
|
||||
orderBy: { createdAt: 'asc' },
|
||||
take: 50,
|
||||
});
|
||||
return swaps
|
||||
.map(w => ({ w, shift: shiftOf(w.role, w.role.event) }))
|
||||
.filter(({ shift }) => shift.endsAt > new Date(now))
|
||||
.map(({ w, shift }) => ({
|
||||
swapId: w.id, note: w.note || '', from: (w.fromUser?.name || '').split(' ')[0] || null,
|
||||
role: { id: w.role.id, name: w.role.name, sessionLabel: w.role.session ? sessionsUtil.sessionLabel(w.role.session, w.role.event.sessions) : null },
|
||||
event: { id: w.role.event.id, title: w.role.event.title },
|
||||
shift: { startsAt: shift.startsAt, endsAt: shift.endsAt, text: shiftText(shift) },
|
||||
}));
|
||||
}
|
||||
|
||||
// ─── Check-in ─────────────────────────────────────────────────────────────────
|
||||
|
||||
/** Put a checked-in volunteer of a kids-room role on duty in that room for the occasion. */
|
||||
async function startKidsDuty(tx, event, role, userId, now) {
|
||||
if (!role.kidsRoomId || !event.kidsCheckIn || !event.kidsRoomSetId) return false;
|
||||
const room = await tx.allocationGroup.findFirst({ where: { id: role.kidsRoomId, setId: event.kidsRoomSetId }, select: { id: true } });
|
||||
if (!room) return false;
|
||||
const occasion = kidsOccasion(role, now);
|
||||
const already = await tx.kidsRoomDuty.findFirst({ where: { userId, occasion, roomId: room.id, endedAt: null } });
|
||||
if (already) return true;
|
||||
// One room at a time, as with "I'm on duty".
|
||||
await tx.kidsRoomDuty.updateMany({ where: { userId, occasion, endedAt: null }, data: { endedAt: new Date(now) } });
|
||||
await tx.kidsRoomDuty.create({ data: { roomId: room.id, occasion, userId, fromRoster: true, startedAt: new Date(now) } });
|
||||
return true;
|
||||
}
|
||||
|
||||
async function markCheckedIn(tx, event, slot, { by, method, now }) {
|
||||
await tx.volunteerSlot.update({ where: { id: slot.id }, data: { checkedInAt: new Date(now), checkedInById: by, checkInMethod: method } });
|
||||
return startKidsDuty(tx, event, slot.role, slot.userId, now);
|
||||
}
|
||||
|
||||
/**
|
||||
* A volunteer scanned the event's check-in QR code: check in every slot of theirs whose shift is
|
||||
* on today. Returns { event, checkedIn: [{ role, kidsRoom }], already }.
|
||||
*/
|
||||
async function checkInWithQr({ qr, userId, now = new Date() }, db = prisma) {
|
||||
const token = String(qr || '').trim().replace(new RegExp(`^${QR_PREFIX}`, 'i'), '');
|
||||
const found = token ? await db.event.findUnique({ where: { volunteerCheckInToken: token }, select: { id: true } }) : null;
|
||||
if (!found) throw volunteerError('That isn\'t a volunteer check-in code from this site.', 404, 'BAD_QR');
|
||||
const event = await loadEvent(found.id, db);
|
||||
const slots = await db.volunteerSlot.findMany({ where: { userId, role: { eventId: event.id } }, include: { role: { include: { session: true, kidsRoom: { select: { name: true } } } } } });
|
||||
if (!slots.length) throw volunteerError(`You're not on the volunteer roster for ${event.title}.`, 404, 'NOT_ROSTERED');
|
||||
const today = slots.filter(s => !s.role.session?.cancelledAt && checkInOpen(shiftOf(s.role, event), now));
|
||||
if (!today.length) {
|
||||
const next = slots.map(s => shiftOf(s.role, event)).filter(sh => sh.endsAt > new Date(now)).sort((a, b) => a.startsAt - b.startsAt)[0];
|
||||
throw volunteerError(next ? `Check-in opens on the day of your shift (${shiftText(next)}).` : 'Your shifts at this event are over.', 400, 'NOT_TODAY');
|
||||
}
|
||||
const checkedIn = [];
|
||||
const already = [];
|
||||
await db.$transaction(async tx => {
|
||||
for (const s of today) {
|
||||
if (s.checkedInAt) { already.push(s.role.name); continue; }
|
||||
const onDuty = await markCheckedIn(tx, event, s, { by: userId, method: 'qr', now });
|
||||
checkedIn.push({ role: s.role.name, kidsRoom: onDuty ? s.role.kidsRoom?.name || null : null });
|
||||
}
|
||||
});
|
||||
return { event: { id: event.id, title: event.title }, checkedIn, already };
|
||||
}
|
||||
|
||||
/** Staff tick a volunteer in (or undo it, which also ends their rostered kids-room duty). */
|
||||
async function checkInManual({ slotId, staffUserId, undo = false, now = new Date() }, db = prisma) {
|
||||
const slot = await loadSlot(slotId, db);
|
||||
const event = await loadEvent(slot.role.eventId, db);
|
||||
if (undo) {
|
||||
if (!slot.checkedInAt) return { slot, changed: false };
|
||||
await db.$transaction(async tx => {
|
||||
await tx.volunteerSlot.update({ where: { id: slot.id }, data: { checkedInAt: null, checkedInById: null, checkInMethod: null } });
|
||||
if (slot.role.kidsRoomId) await tx.kidsRoomDuty.updateMany({ where: { userId: slot.userId, roomId: slot.role.kidsRoomId, fromRoster: true, endedAt: null }, data: { endedAt: new Date(now) } });
|
||||
});
|
||||
return { slot, changed: true };
|
||||
}
|
||||
if (slot.checkedInAt) return { slot, changed: false };
|
||||
if (!checkInOpen(shiftOf(slot.role, event), now) && new Date(now) < shiftOf(slot.role, event).startsAt) {
|
||||
throw volunteerError(`${slot.user.name} can be checked in on the day of the shift (${shiftText(shiftOf(slot.role, event))}).`);
|
||||
}
|
||||
await db.$transaction(tx => markCheckedIn(tx, event, slot, { by: staffUserId, method: 'manual', now }));
|
||||
return { slot, changed: true };
|
||||
}
|
||||
|
||||
/** For the kids board: who is rostered in each room for an occasion, and whether they've checked in. */
|
||||
async function rosteredForRooms(event, occasion, db = prisma) {
|
||||
if (!event.kidsRoomSetId) return {};
|
||||
const roles = await db.servingRole.findMany({
|
||||
where: { eventId: event.id, kidsRoom: { setId: event.kidsRoomSetId }, ...(event.scheduleType === 'sessions' ? { sessionId: occasion } : {}) },
|
||||
include: { session: true, slots: { include: { user: { select: { id: true, name: true } } } } },
|
||||
});
|
||||
const out = {};
|
||||
for (const r of roles) {
|
||||
// Single-date events: only roles whose shift is on that day.
|
||||
if (event.scheduleType !== 'sessions') {
|
||||
const shift = shiftOf(r, event);
|
||||
if (occasion < sessionsUtil.dayKey(shift.startsAt) || occasion > sessionsUtil.dayKey(shift.endsAt)) continue;
|
||||
}
|
||||
for (const s of r.slots) {
|
||||
(out[r.kidsRoomId] ||= []).push({ userId: s.user.id, name: s.user.name, checkedIn: !!s.checkedInAt });
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// ─── My serving ───────────────────────────────────────────────────────────────
|
||||
|
||||
/** The person's upcoming (and the last week's) slots, with open swap requests. */
|
||||
async function mySlots({ userId, now = new Date() }, db = prisma) {
|
||||
const since = new Date(new Date(now).getTime() - 7 * 24 * HOUR);
|
||||
const slots = await db.volunteerSlot.findMany({
|
||||
where: { userId, role: { event: { endDate: { gte: since } } } },
|
||||
include: { role: { include: { session: true, kidsRoom: { select: { name: true } }, event: { select: EVENT_SELECT } } }, swaps: { where: { status: 'open' } } },
|
||||
});
|
||||
return slots
|
||||
.map(s => {
|
||||
const shift = shiftOf(s.role, s.role.event);
|
||||
return {
|
||||
slotId: s.id,
|
||||
role: { id: s.role.id, name: s.role.name, description: s.role.description || '', sessionLabel: s.role.session ? sessionsUtil.sessionLabel(s.role.session, s.role.event.sessions) : null, kidsRoom: s.role.kidsRoom?.name || null },
|
||||
event: { id: s.role.event.id, title: s.role.event.title, location: s.role.event.location },
|
||||
shift: { startsAt: shift.startsAt, endsAt: shift.endsAt, text: shiftText(shift), hours: shiftHours(shift) },
|
||||
checkedInAt: s.checkedInAt,
|
||||
canCheckIn: !s.checkedInAt && checkInOpen(shift, now),
|
||||
past: shift.endsAt < new Date(now),
|
||||
swapId: s.swaps[0]?.id || null,
|
||||
hasTicket: !!s.registrationId,
|
||||
};
|
||||
})
|
||||
.sort((a, b) => new Date(a.shift.startsAt) - new Date(b.shift.startsAt));
|
||||
}
|
||||
|
||||
/** Upcoming events with serving roles (for "Serve at an event"). */
|
||||
async function eventsWithRoles({ now = new Date(), where = {} } = {}, db = prisma) {
|
||||
return db.event.findMany({
|
||||
where: { AND: [{ isActive: true, endDate: { gte: now }, servingRoles: { some: {} } }, where] },
|
||||
select: { id: true, title: true, startDate: true, endDate: true, location: true, campusId: true, isHidden: true, _count: { select: { servingRoles: true } } },
|
||||
orderBy: { startDate: 'asc' },
|
||||
take: 100,
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Reports ──────────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Hours served per person over the events matching `eventWhere` (checked-in shifts only), most
|
||||
* hours first: [{ userId, name, shifts, hours, events }].
|
||||
*/
|
||||
async function hoursServed({ eventWhere = {}, from = null, to = null } = {}, db = prisma) {
|
||||
const slots = await db.volunteerSlot.findMany({
|
||||
where: { checkedInAt: { not: null, ...(from ? { gte: new Date(from) } : {}), ...(to ? { lte: new Date(to) } : {}) }, role: { event: eventWhere } },
|
||||
include: { user: { select: { id: true, name: true } }, role: { include: { session: true, event: { select: { id: true, startDate: true, endDate: true, sessions: true } } } } },
|
||||
});
|
||||
const byUser = new Map();
|
||||
for (const s of slots) {
|
||||
const row = byUser.get(s.userId) || { userId: s.userId, name: s.user.name, shifts: 0, hours: 0, events: new Set() };
|
||||
row.shifts += 1;
|
||||
row.hours += shiftHours(shiftOf(s.role, s.role.event));
|
||||
row.events.add(s.role.event.id);
|
||||
byUser.set(s.userId, row);
|
||||
}
|
||||
return [...byUser.values()].map(r => ({ ...r, events: r.events.size })).sort((a, b) => b.hours - a.hours || a.name.localeCompare(b.name));
|
||||
}
|
||||
|
||||
// ─── Messages ─────────────────────────────────────────────────────────────────
|
||||
|
||||
function frontendUrl() {
|
||||
return String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
|
||||
}
|
||||
|
||||
const servingUrl = () => `${frontendUrl()}/dashboard/user/serving`;
|
||||
|
||||
/** Send a text to a volunteer the way they like it (WhatsApp, email, or whichever works). Fire-and-forget. */
|
||||
function tell(user, { subject, heading, text }) {
|
||||
if (!user) return Promise.resolve([]);
|
||||
return require('./kids').messageParent(user, { subject, heading, text }).catch(() => []);
|
||||
}
|
||||
|
||||
/** Email the event's notify recipients (or its creator) about a roster change. */
|
||||
async function tellOrganisers(eventId, { subject, text }, db = prisma) {
|
||||
const event = await db.event.findUnique({
|
||||
where: { id: eventId },
|
||||
include: { createdBy: { select: { email: true } }, notifyRecipients: { select: { email: true } } },
|
||||
});
|
||||
const to = require('./notifications').getEventNotifyEmails(event);
|
||||
if (!to.length) return;
|
||||
const { sendMail, buildPrivacyEmail } = require('./email');
|
||||
await sendMail({ to: to.join(','), subject, ...buildPrivacyEmail({ name: 'team', heading: subject, paragraphs: [text, `Roster: ${frontendUrl()}/dashboard/supervisor/volunteers?event=${eventId}`] }) }).catch(() => {});
|
||||
}
|
||||
|
||||
function placeText(role, event) {
|
||||
return `${role.name} at ${event.title}${role.session ? ` (${sessionsUtil.sessionLabel(role.session, event.sessions)})` : ''}, ${shiftText(shiftOf(role, event))}`;
|
||||
}
|
||||
|
||||
function signedUpMessages({ user, role, event, by = null }) {
|
||||
const text = by
|
||||
? `${by} has put you on the volunteer roster: ${placeText(role, event)}. Thank you for serving! If you can't make it, ask for cover in My account → Serving (${servingUrl()}).`
|
||||
: `Thank you for volunteering: ${placeText(role, event)}. You'll get a reminder the day before. If you can't make it, ask for cover in My account → Serving (${servingUrl()}).`;
|
||||
return tell(user, { subject: `Serving: ${role.name} — ${event.title}`, heading: 'You\'re on the roster', text });
|
||||
}
|
||||
|
||||
/** The cover request goes to the event's other volunteers (not the ones already in this role). */
|
||||
async function sendSwapRequest({ swap, slot, event }, db = prisma) {
|
||||
const others = await db.volunteerSlot.findMany({
|
||||
where: { role: { eventId: event.id }, userId: { not: slot.userId }, NOT: { roleId: slot.roleId } },
|
||||
distinct: ['userId'],
|
||||
include: { user: { select: USER_SELECT } },
|
||||
take: 200,
|
||||
});
|
||||
const inRole = new Set((await db.volunteerSlot.findMany({ where: { roleId: slot.roleId }, select: { userId: true } })).map(s => s.userId));
|
||||
const first = (slot.user.name || '').split(' ')[0] || 'A volunteer';
|
||||
const text = `${first} can't make it and is looking for someone to take over: ${placeText(slot.role, event)}.${swap.note ? ` "${swap.note}"` : ''} If you can, take it over in My account → Serving (${servingUrl()}) — the first to accept gets it.`;
|
||||
for (const o of others) {
|
||||
if (inRole.has(o.userId)) continue;
|
||||
await tell(o.user, { subject: `Cover needed: ${slot.role.name} — ${event.title}`, heading: 'Can you take over?', text });
|
||||
}
|
||||
return others.length;
|
||||
}
|
||||
|
||||
async function sendSwapAccepted({ slot, from, to, event }) {
|
||||
const what = placeText(slot.role, event);
|
||||
await tell(from, { subject: `${to.name} is taking over — ${event.title}`, heading: 'Your place is covered', text: `${to.name} has taken over ${what}. You're off the roster for it — thank you for finding cover.` });
|
||||
await tell(to, { subject: `Serving: ${slot.role.name} — ${event.title}`, heading: 'You\'re on the roster', text: `Thank you for taking over from ${from.name}: ${what}. You'll get a reminder the day before.` });
|
||||
await tellOrganisers(event.id, { subject: `Roster swap: ${slot.role.name} — ${event.title}`, text: `${to.name} has taken over from ${from.name}: ${what}.` });
|
||||
}
|
||||
|
||||
async function sendLeft({ slot, event, byStaff = null }) {
|
||||
const what = placeText(slot.role, event);
|
||||
if (byStaff) {
|
||||
await tell(slot.user, { subject: `Roster change — ${event.title}`, heading: 'Roster change', text: `${byStaff} has taken you off the roster for ${what}. Thank you for being willing to serve.` });
|
||||
} else {
|
||||
await tellOrganisers(event.id, { subject: `Volunteer withdrew: ${slot.role.name} — ${event.title}`, text: `${slot.user.name} has withdrawn from ${what}.` });
|
||||
}
|
||||
}
|
||||
|
||||
async function sendRoleDeleted({ role, event, volunteers }) {
|
||||
for (const u of volunteers) {
|
||||
await tell(u, { subject: `Roster change — ${event.title}`, heading: 'Roster change', text: `The ${role.name} role at ${event.title} is no longer needed, so you're off the roster for it. Thank you for being willing to serve.` });
|
||||
}
|
||||
}
|
||||
|
||||
/** Reminders for shifts starting within the next 24 hours. Returns { sent }. */
|
||||
async function runReminderJob(now = new Date(), db = prisma) {
|
||||
const slots = await db.volunteerSlot.findMany({
|
||||
where: { remindedAt: null, checkedInAt: null, role: { event: { isActive: true, endDate: { gte: now }, startDate: { lte: new Date(new Date(now).getTime() + 31 * 24 * HOUR) } } } },
|
||||
include: { user: { select: USER_SELECT }, role: { include: { session: true, event: { select: EVENT_SELECT } } } },
|
||||
take: 2000,
|
||||
});
|
||||
let sent = 0;
|
||||
for (const s of slots) {
|
||||
if (s.role.session?.cancelledAt) continue;
|
||||
const shift = shiftOf(s.role, s.role.event);
|
||||
if (!reminderDue(s, shift, now)) continue;
|
||||
// Claim it first so a second backend process doesn't send it again.
|
||||
const claimed = await db.volunteerSlot.updateMany({ where: { id: s.id, remindedAt: null }, data: { remindedAt: new Date(now) } });
|
||||
if (!claimed.count) continue;
|
||||
const ev = s.role.event;
|
||||
const place = ev.location ? ` at ${ev.location}` : '';
|
||||
await tell(s.user, {
|
||||
subject: `Reminder: serving ${s.role.name} — ${ev.title}`,
|
||||
heading: 'See you soon',
|
||||
text: `A reminder that you're serving: ${placeText(s.role, ev)}${place}. When you arrive, scan the volunteer check-in QR code with your phone. Can't make it? Ask for cover in My account → Serving (${servingUrl()}).`,
|
||||
});
|
||||
sent += 1;
|
||||
}
|
||||
return { sent };
|
||||
}
|
||||
|
||||
// ─── Privacy ──────────────────────────────────────────────────────────────────
|
||||
|
||||
/** For "Download my data". */
|
||||
async function exportVolunteering(userId, db = prisma) {
|
||||
const slots = await db.volunteerSlot.findMany({
|
||||
where: { userId },
|
||||
include: { role: { include: { session: true, event: { select: { title: true, startDate: true, endDate: true, sessions: true } } } } },
|
||||
orderBy: { createdAt: 'asc' },
|
||||
});
|
||||
return slots.map(s => {
|
||||
const shift = shiftOf(s.role, s.role.event);
|
||||
return { event: s.role.event.title, role: s.role.name, from: shift.startsAt, to: shift.endsAt, signedUp: s.createdAt, assigned: !!s.assignedById, checkedIn: s.checkedInAt };
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* For anonymiseUser: shifts still to come are given up (open places, free tickets released);
|
||||
* past ones stay for the hours-served totals, under the anonymised account. Swap notes go.
|
||||
*/
|
||||
async function forgetVolunteer(tx, userId, now = new Date()) {
|
||||
const slots = await tx.volunteerSlot.findMany({ where: { userId, checkedInAt: null }, include: { role: { include: { session: true, event: { select: { startDate: true, endDate: true, sessions: true } } } } } });
|
||||
let removed = 0;
|
||||
for (const s of slots) {
|
||||
if (shiftOf(s.role, s.role.event).endsAt <= new Date(now)) continue;
|
||||
await tx.volunteerSwap.updateMany({ where: { slotId: s.id, status: 'open' }, data: { status: 'cancelled', resolvedAt: new Date(now) } });
|
||||
await releasePlace(tx, s);
|
||||
await tx.volunteerSlot.delete({ where: { id: s.id } });
|
||||
removed += 1;
|
||||
}
|
||||
await tx.volunteerSwap.updateMany({ where: { OR: [{ fromUserId: userId }, { toUserId: userId }], note: { not: null } }, data: { note: null } });
|
||||
return removed;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
QR_PREFIX, MAX_NEEDED, volunteerError,
|
||||
shiftOf, overlaps, shiftHours, fillOf, checkInOpen, reminderDue, kidsOccasion, reservedOptionIds, publicOptions, shiftText,
|
||||
loadEvent, roleView, roster, createRole, updateRole, deleteRole, getSettings, saveSettings, checkInQr,
|
||||
givePlace, releasePlace, signUp, leave, requestSwap, cancelSwap, acceptSwap, openSwaps,
|
||||
checkInWithQr, checkInManual, rosteredForRooms, mySlots, eventsWithRoles, hoursServed,
|
||||
signedUpMessages, sendSwapRequest, sendSwapAccepted, sendLeft, sendRoleDeleted, runReminderJob,
|
||||
exportVolunteering, forgetVolunteer,
|
||||
};
|
||||
@@ -0,0 +1,92 @@
|
||||
const v = require('../src/utils/volunteers');
|
||||
const { isBlocked } = require('../src/hub/readOnly');
|
||||
|
||||
const event = {
|
||||
id: 'e1', startDate: new Date('2026-11-08T06:00:00Z'), endDate: new Date('2026-11-08T10:00:00Z'),
|
||||
sessions: [{ id: 's1', startsAt: new Date('2026-11-15T16:30:00Z'), endsAt: new Date('2026-11-15T18:30:00Z') }],
|
||||
};
|
||||
|
||||
describe('shifts', () => {
|
||||
test("a role's shift: its own times, else its session's, else the event's", () => {
|
||||
expect(v.shiftOf({}, event)).toEqual({ startsAt: event.startDate, endsAt: event.endDate });
|
||||
expect(v.shiftOf({ sessionId: 's1' }, event)).toEqual({ startsAt: event.sessions[0].startsAt, endsAt: event.sessions[0].endsAt });
|
||||
const own = { startsAt: '2026-11-08T05:30:00Z', endsAt: '2026-11-08T07:00:00Z' };
|
||||
expect(v.shiftOf(own, event)).toEqual({ startsAt: new Date(own.startsAt), endsAt: new Date(own.endsAt) });
|
||||
});
|
||||
|
||||
test('overlapping shifts; touching ends are fine', () => {
|
||||
const a = { startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T08:00:00Z' };
|
||||
expect(v.overlaps(a, { startsAt: '2026-11-08T07:00:00Z', endsAt: '2026-11-08T09:00:00Z' })).toBe(true);
|
||||
expect(v.overlaps(a, { startsAt: '2026-11-08T08:00:00Z', endsAt: '2026-11-08T09:00:00Z' })).toBe(false);
|
||||
expect(v.overlaps(a, { startsAt: '2026-11-08T05:00:00Z', endsAt: '2026-11-08T06:00:00Z' })).toBe(false);
|
||||
});
|
||||
|
||||
test('hours to the nearest quarter hour', () => {
|
||||
expect(v.shiftHours({ startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T08:30:00Z' })).toBe(2.5);
|
||||
expect(v.shiftHours({ startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T06:50:00Z' })).toBe(0.75);
|
||||
expect(v.shiftHours({ startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T06:00:00Z' })).toBe(0);
|
||||
});
|
||||
|
||||
test('fill', () => {
|
||||
expect(v.fillOf(4, 3)).toEqual({ needed: 4, filled: 3, open: 1, full: false });
|
||||
expect(v.fillOf(2, 3)).toEqual({ needed: 2, filled: 3, open: 0, full: true });
|
||||
});
|
||||
});
|
||||
|
||||
describe('check-in window', () => {
|
||||
const shift = { startsAt: new Date('2026-11-08T06:00:00Z'), endsAt: new Date('2026-11-08T08:00:00Z') };
|
||||
test('open on the day of the shift until it ends', () => {
|
||||
expect(v.checkInOpen(shift, new Date('2026-11-08T04:00:00Z'))).toBe(true); // early, same day (SAST)
|
||||
expect(v.checkInOpen(shift, new Date('2026-11-08T07:59:00Z'))).toBe(true);
|
||||
});
|
||||
test('closed the day before and after the shift ends', () => {
|
||||
expect(v.checkInOpen(shift, new Date('2026-11-07T12:00:00Z'))).toBe(false);
|
||||
expect(v.checkInOpen(shift, new Date('2026-11-08T08:01:00Z'))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('reminders', () => {
|
||||
const shift = { startsAt: new Date('2026-11-08T06:00:00Z'), endsAt: new Date('2026-11-08T08:00:00Z') };
|
||||
const signedUp = new Date('2026-11-01T10:00:00Z');
|
||||
test('due within 24 hours of the start, once', () => {
|
||||
expect(v.reminderDue({ remindedAt: null, createdAt: signedUp }, shift, new Date('2026-11-07T07:00:00Z'))).toBe(true);
|
||||
expect(v.reminderDue({ remindedAt: new Date(), createdAt: signedUp }, shift, new Date('2026-11-07T07:00:00Z'))).toBe(false);
|
||||
});
|
||||
test('not too early, not after the start', () => {
|
||||
expect(v.reminderDue({ remindedAt: null, createdAt: signedUp }, shift, new Date('2026-11-07T05:00:00Z'))).toBe(false);
|
||||
expect(v.reminderDue({ remindedAt: null, createdAt: signedUp }, shift, new Date('2026-11-08T06:00:00Z'))).toBe(false);
|
||||
});
|
||||
test('not for someone who signed up minutes ago', () => {
|
||||
const now = new Date('2026-11-07T20:00:00Z');
|
||||
expect(v.reminderDue({ remindedAt: null, createdAt: new Date(now.getTime() - 10 * 60 * 1000) }, shift, now)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('kids rooms', () => {
|
||||
test('a session role counts for its session; otherwise for the day', () => {
|
||||
expect(v.kidsOccasion({ sessionId: 's1' })).toBe('s1');
|
||||
expect(v.kidsOccasion({ sessionId: null }, new Date('2026-11-08T06:00:00Z'))).toBe('2026-11-08');
|
||||
});
|
||||
});
|
||||
|
||||
describe('reserved tickets', () => {
|
||||
test('the kids and volunteer tickets never show publicly', () => {
|
||||
const ev = { kidsOptionId: 'k', volunteerOptionId: 'vol', eventOptions: [{ id: 'adult' }, { id: 'k' }, { id: 'vol' }] };
|
||||
expect(v.reservedOptionIds(ev)).toEqual(['k', 'vol']);
|
||||
expect(v.publicOptions(ev).map(o => o.id)).toEqual(['adult']);
|
||||
expect(v.publicOptions({ eventOptions: [{ id: 'a' }] }).map(o => o.id)).toEqual(['a']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('read-only licence', () => {
|
||||
test.each([
|
||||
['POST', '/api/volunteers/roles/r1/sign-up'],
|
||||
['POST', '/api/volunteers/manage/events/e1/roles'],
|
||||
['POST', '/api/volunteers/manage/roles/r1/assign'],
|
||||
])('%s %s is blocked', (m, p) => expect(isBlocked(m, p)).toBe(true));
|
||||
test.each([
|
||||
['POST', '/api/volunteers/check-in'],
|
||||
['POST', '/api/volunteers/swaps/w1/accept'],
|
||||
['DELETE', '/api/volunteers/slots/s1'],
|
||||
])('%s %s keeps working', (m, p) => expect(isBlocked(m, p)).toBe(false));
|
||||
});
|
||||
Reference in New Issue
Block a user