diff --git a/apps/events/CHANGELOG.md b/apps/events/CHANGELOG.md index 8713b75..59b1ba5 100644 --- a/apps/events/CHANGELOG.md +++ b/apps/events/CHANGELOG.md @@ -7,6 +7,44 @@ and this project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] +## [1.46.0] - 2026-10-28 + +### Added + +- **Volunteer rosters** — plan who serves where (Supervisor → **Volunteer rosters**). + - **Serving roles** (Welcome, Parking, Kids, Sound…) per event, or per session on a multi-session + event, with the number of people needed, optional shift times and a short description. Each + event or session has its own roster; nothing repeats by itself. + - **Anyone with an account can volunteer:** My account → **Serving** lists events looking for + people and lets you sign up for a role that isn't full. Supervisors can also put someone on a + role (even beyond the number needed). Nobody can be in two roles at the same time. Supervisors + get a sign-up link to share (it works for hidden events too). + - **Reminders** by WhatsApp or email the day before a shift. + - **"Can't make it" swaps:** the volunteer asks for cover, the event's other volunteers are told, + and the first to accept takes the place straight away — no approval. The event's notification + recipients get an email about every swap and every withdrawal. + - **Check-in on the day:** volunteers scan the event's check-in QR code (show it on a screen or + print it) with their phone camera and are checked in for that day's shifts; staff can tick + people in on Staff → **Volunteers**, and undo it. + - **Kids rooms:** a role can be linked to a kids room. Its volunteers count as leaders on duty + in that room once they check in (for the room's ratio), and the room screen lists who is + rostered but not in yet. + - **Free volunteer ticket**, off by default: choose a ticket per event (or add a free + "Volunteer" ticket) and everyone on the roster gets a free place on it unless they already have + a ticket. It's given back when they leave the roster. + - **Roster sheet** with phone numbers, check-in times and a printable view; fill rate per + event; **hours served** per person across events. + - Audit log entries for the volunteer ticket, role changes, people put on or taken off a roster + and check-ins by hand; opening a roster is in the access log. "Download my data" includes + your shifts; anonymising an account gives up its future shifts. + - Background job `volunteers` (every 15 minutes, `VOLUNTEER_JOBS_ENABLED`) sends the reminders. + +### Fixed + +- **The kids check-in ticket was offered publicly:** the free "Kids check-in" ticket from 1.45.0 + showed on the event page and could be booked by anyone. It (and the new volunteer ticket) is now + left out of public event pages and lists and refused on public registration; staff still see it. + ## [1.45.1] - 2026-10-28 ### Fixed diff --git a/apps/events/FEATURES.md b/apps/events/FEATURES.md index 63ca840..b8b7f38 100644 --- a/apps/events/FEATURES.md +++ b/apps/events/FEATURES.md @@ -31,12 +31,13 @@ WhatsApp · PM2 for process management · optional Sentry for error monitoring. 15. [Site settings & setup wizard](#site-settings--setup-wizard) 16. [Multi-campus](#multi-campus) 17. [Kids check-in](#kids-check-in) -18. [Accounts & security](#accounts--security) -19. [Privacy (POPIA)](#privacy-popia) -20. [Help system](#help-system) -21. [Background jobs](#background-jobs) -22. [Operations](#operations) -23. [Page map](#page-map) +18. [Volunteer rosters](#volunteer-rosters) +19. [Accounts & security](#accounts--security) +20. [Privacy (POPIA)](#privacy-popia) +21. [Help system](#help-system) +22. [Background jobs](#background-jobs) +23. [Operations](#operations) +24. [Page map](#page-map) --- @@ -397,6 +398,8 @@ logout controls. Disconnected sessions are recovered automatically. and print an event's tickets. - **Kids check-in** (`/dashboard/staff/kids`) and the **room screen** (`/dashboard/staff/kids/rooms`) — see [Kids check-in](#kids-check-in). +- **Volunteers** (`/dashboard/staff/volunteers`) — today's roster, ticking volunteers in and the + check-in QR code — see [Volunteer rosters](#volunteer-rosters). --- @@ -594,6 +597,43 @@ label printers. changed only by parents, supervisors and admins (audited); opening the desk/room screens and offline downloads are in the access log; a child's profile is deleted after **6 months** without a check-in (Admin → Privacy → Retention). +- **Volunteers in kids rooms:** a serving role linked to a room puts its volunteers on duty there + when they check in; the room screen lists who is rostered but not in yet. +- The kids ticket is never offered publicly (left out of public event pages, refused on public + registration). + +--- + +## Volunteer rosters + +Who serves where, for an event or each session. + +- **Roles** (Supervisor → Volunteer rosters, `/dashboard/supervisor/volunteers`): name, people + needed, optional shift times (default: the session's or event's times), description, and + optionally a kids room. On a multi-session event each role is for one session. A role can't be + deleted once someone has checked in for it. +- **Volunteering** (My account → Serving, `/dashboard/user/serving`): anyone with an account signs + up for a role that isn't full; supervisors can also put people on (beyond the number needed). + Nobody can be in two roles whose shifts overlap. `?event=` opens one event (the sign-up link + supervisors share, also for hidden events). Volunteers are told when they're put on, taken off, + or a role is deleted, and get a **reminder the day before**. +- **Swaps:** "Can't make it" asks for cover — the event's other volunteers are told and the request + shows on everyone's Serving page; the first to accept takes the place at once (no approval). The + event's notification recipients (or its creator) are emailed about every swap and withdrawal. +- **Check-in:** volunteers scan the event's **check-in QR code** (Check-in QR tab, or Staff → + Volunteers) with their phone camera → `/serve/check-in` → every shift of theirs on that day is + checked in. Staff can tick people in by hand (and undo). Check-in opens on the day of the shift + and closes when it ends. +- **Kids rooms:** checking in for a role linked to a kids room puts the volunteer on duty in that + room (counted for the ratio, like "I'm on duty"); undoing the check-in takes them off. +- **Volunteer ticket** (off by default): choose a main ticket of the event, or add a free + "Volunteer" ticket. Volunteers without a ticket get a free place on it (in My Events); it's + cancelled when they leave the roster (unless it was scanned), moves with a swap, and is never + offered publicly. +- **Reports:** roster sheet (phone numbers, check-in time and how), printable; fill rate per event; + **hours served** per person (checked-in shifts × shift length) over all events or one. +- **Read-only licence:** new roles and sign-ups are blocked; check-ins, swaps and withdrawals keep + working. --- @@ -713,6 +753,7 @@ can't start, the same jobs run on in-process timers. | `payment-status` — look up PayFast checkouts (10 min – 3 days old) whose notification never arrived, and record them | Every 15 minutes (`PAYMENT_STATUS_JOB_ENABLED=false`) | | `feedback` — post-event feedback forms and their 3-day reminder | Every 15 minutes (`FEEDBACK_JOB_ENABLED=false`) | | `sessions` — session reminders, and certificates for events that ended in the last 14 days | Every 5 minutes (`SESSION_JOBS_ENABLED=false`) | +| `volunteers` — volunteer reminders the day before a shift | Every 15 minutes (`VOLUNTEER_JOBS_ENABLED=false`) | | `consent` — parental consent reminders, and deleting medical details after events | 09:00 daily (`CONSENT_JOBS_ENABLED=false`) | | `privacy` — remind admins of privacy requests due within a week or overdue | 08:00 daily (`PRIVACY_JOBS_ENABLED=false`) | | `retention` — delete/anonymise personal information past its retention period (Admin → Privacy → Retention) | 03:30 daily (`RETENTION_JOBS_ENABLED=false`) | @@ -777,9 +818,10 @@ can't start, the same jobs run on in-process timers. | `/waitlist/claim/[token]` | Public | Claim a waitlist place | | `/certificates/verify/[code]` | Public | Check a completion certificate | | `/unsubscribe?t=…` | Public | Unsubscribe from news (link in news emails/WhatsApps) | +| `/serve/check-in?code=…` | User (logs in first) | Volunteer check-in (where the event's check-in QR code leads) | | `/self-service` | Supervisor-unlocked | Kiosk | | `/set-banner` | Supervisor | Site banner | -| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/privacy`, `/kids`, `/reset-password`) | User | My Events | -| `/dashboard/staff` (+ `/ticket-scanning`, `/event-tickets`, `/my-groups`, `/kids`, `/kids/rooms`) | Staff | Staff tools | -| `/dashboard/supervisor` (+ `/events`, `/event-options`, `/at-the-door`, `/manual`, `/manual-registration`, `/payments`, `/coupons`, `/waitlist`, `/attendance`, `/consent`, `/offline-scans`, `/allocations`, `/kids`, `/email-attendees`, `/whatsapp-attendees`, `/forms`, `/reports`) | Supervisor | Supervisor tools | +| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/privacy`, `/kids`, `/serving`, `/reset-password`) | User | My Events | +| `/dashboard/staff` (+ `/ticket-scanning`, `/event-tickets`, `/my-groups`, `/kids`, `/kids/rooms`, `/volunteers`) | Staff | Staff tools | +| `/dashboard/supervisor` (+ `/events`, `/event-options`, `/at-the-door`, `/manual`, `/manual-registration`, `/payments`, `/coupons`, `/waitlist`, `/attendance`, `/consent`, `/offline-scans`, `/allocations`, `/kids`, `/volunteers`, `/email-attendees`, `/whatsapp-attendees`, `/forms`, `/reports`) | Supervisor | Supervisor tools | | `/dashboard/admin` (+ `/users`, `/registrations`, `/forms`, `/cashup`, `/cashup/[id]`, `/audit-log`, `/data-requests`, `/privacy`, `/settings`) | Admin | Admin tools | diff --git a/apps/events/SETTINGS.md b/apps/events/SETTINGS.md index ad5ab34..3c704ca 100644 --- a/apps/events/SETTINGS.md +++ b/apps/events/SETTINGS.md @@ -116,6 +116,7 @@ Managed in the Payments tab (through `/api/payments/providers/settings` and `/ap | `PRIVACY_JOBS_ENABLED` (env) | `true` | The daily 08:00 `privacy` job that reminds admins of requests due within a week or overdue. | | `retention_policies` | Inactive accounts 60 months (on), form answers 12, login history 24, payment details 24, children at kids check-in (`kids_profiles`) 6, audit/access logs 60 — all on | Admin → Privacy → Retention (JSON `{ policies: { key: { enabled, months } }, reviewedAt, reviewedBy }`). Minimums: inactive accounts and logs 12 months, login history and payment details 3, form answers and kids profiles 1; maximum 240. Saving marks them reviewed (readiness check). | | `retention_last_run` | — | When the `retention` job last ran and what it did (readiness check: within 2 days). | +| `VOLUNTEER_JOBS_ENABLED` (env) | `true` | The `volunteers` job (every 15 minutes) that sends volunteer reminders the day before a shift. | | `RETENTION_JOBS_ENABLED` (env) | `true` | The nightly 03:30 `retention` job. Off means nothing expires automatically. | | `wawp_webhook_last_seen` | — | Set when WAWP's webhook arrives with the right secret; the readiness page uses it to check WhatsApp STOP is set up. | | `privacy_notice_draft` | — | The unpublished draft from Admin → Privacy → Privacy notice (JSON). Published versions are in the `PrivacyNotice` table. With no published version the built-in notice (`backend/src/utils/privacyNotice.js`) is shown. The notice's org name, Information Officer, website, emails and medical retention days come from the settings above when it's shown. | diff --git a/apps/events/backend/.env.example b/apps/events/backend/.env.example index d4bd2ed..5eaf7a7 100644 --- a/apps/events/backend/.env.example +++ b/apps/events/backend/.env.example @@ -75,6 +75,8 @@ WAITLIST_JOB_ENABLED=true # WAITLIST_JOB_INTERVAL_MS=600000 # Payments: every 15 minutes, look up PayFast checkouts whose notification never arrived PAYMENT_STATUS_JOB_ENABLED=true +# Volunteer rosters: reminders the day before a shift (every 15 minutes) +VOLUNTEER_JOBS_ENABLED=true # Privacy (POPIA): daily 08:00 reminder to admins of data requests due within a week PRIVACY_JOBS_ENABLED=true # Privacy (POPIA): nightly 03:30 retention job (Admin → Privacy → Retention). Note: inactive diff --git a/apps/events/backend/API_DOCUMENTATION.md b/apps/events/backend/API_DOCUMENTATION.md index ae90764..fc51f15 100644 --- a/apps/events/backend/API_DOCUMENTATION.md +++ b/apps/events/backend/API_DOCUMENTATION.md @@ -922,6 +922,41 @@ Allergies, medical and custody notes are stored encrypted. Staff routes are camp | GET | `/api/kids/events/:eventId/offline?deviceId=&sessionId=` | staff+ | Offline snapshot: board plus `families` and `codes` (20 reserved for the device). Access log `kids_offline` | | POST | `/api/kids/events/:eventId/sync` | staff+ | `{ deviceId, occasion, checkIns: [{ clientId, familyId, childId, roomId, code, at }], checkOuts: [{ clientId, collectedBy, at }] }` → `{ checkedIn, checkedOut, conflicts }`; idempotent by `clientId`; audited as `kids_offline_sync` | +Since 1.46.0 board rooms also carry `rostered: [{ userId, name, checkedIn }]` (volunteers on a serving +role linked to the room); checked-in ones are counted in `leaders`. + +## Volunteer rosters + +Volunteer rosters (1.46.0, `src/utils/volunteers.js`). A **serving role** belongs to an event, or to +one session of a multi-session event (`sessionId` required there), with `needed` people and optional +`startsAt`/`endsAt` (default: the session's or event's times). A **slot** is a person on a role; +nobody can hold two slots whose shifts overlap (`409 SHIFT_CLASH`). When `Event.volunteerOptionId` +is set, each volunteer without a ticket gets a free place on it (cancelled when they leave, moved +with a swap). `volunteerOptionId` and `kidsOptionId` are left out of public event pages +(`GET /api/events`, `GET /api/events/:id` for non-staff) and refused on public registration. Staff +routes are campus-scoped. + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/api/volunteers/me` | user | `{ slots, cover, events }` — my shifts (upcoming and the last week; `canCheckIn`, `swapId`, `hasTicket`), open cover requests I could take, and public events with roles | +| GET | `/api/volunteers/events/:eventId` | user | `{ event, sessions, roles, totals }` — each role with `shift`, `needed`, `filled`, `full`, `mine`, `coverNeeded` (no names) | +| POST | `/api/volunteers/roles/:id/sign-up` | user | `201 { slotId, ticket }`; `409 ROLE_FULL`, `409 SHIFT_CLASH`. Blocked in licence read-only mode | +| DELETE | `/api/volunteers/slots/:id` | user | Withdraw (not after check-in or once the shift is over); the event's notify recipients are emailed | +| POST | `/api/volunteers/slots/:id/swap` | user | `{ note? }` → `{ swapId }` — "can't make it"; the event's other volunteers are told | +| DELETE | `/api/volunteers/swaps/:id` | user | Cancel my cover request | +| POST | `/api/volunteers/swaps/:id/accept` | user | Take the place over at once → `{ slotId, role, event }`; `409 SWAP_CLOSED` if someone was first. Both volunteers and the event's notify recipients are told | +| POST | `/api/volunteers/check-in` | user | `{ qr }` (`SERVE-`) → `{ event, checkedIn: [{ role, kidsRoom }], already }` for my shifts on today. `404 BAD_QR`, `404 NOT_ROSTERED`, `400 NOT_TODAY`. A kids-room role starts a `KidsRoomDuty` (`fromRoster`) | +| GET | `/api/volunteers/manage/events?all=1` | staff+ | Events with roles from the last 30 days on; `all=1` (supervisors) every upcoming event | +| GET | `/api/volunteers/manage/events/:eventId?log=1` | staff+ | The roster with `volunteers: [{ slotId, name, phone, email, checkedInAt, checkInMethod, swapOpen, hasTicket }]` per role, and `totals: { needed, filled, checkedIn, fillRate }`. `log=1` writes the access log (`volunteer_roster`) | +| GET | `/api/volunteers/manage/events/:eventId/qr` | staff+ | `{ token, qr }` — the check-in QR value (the page encodes `/serve/check-in?code=`) | +| POST | `/api/volunteers/manage/slots/:id/check-in` | staff+ | `{ undo? }` — check in by hand (or undo, which ends rostered kids-room duty). Audited as `volunteer_checked_in_manual` | +| GET / PUT | `/api/volunteers/manage/events/:eventId/settings` | supervisor+ | `{ optionId }` — the volunteer ticket: a main ticket covering the whole event, `'new'` for a free "Volunteer" ticket, `null` = off (default). Also returns the event's `kidsRooms`. Audited as `volunteer_settings_updated` | +| POST | `/api/volunteers/manage/events/:eventId/roles` | supervisor+ | `{ name, needed, sessionId?, startsAt?, endsAt?, description?, kidsRoomId? }`. Audited as `volunteer_roles_changed`; blocked in read-only mode | +| PUT / DELETE | `/api/volunteers/manage/roles/:id` | supervisor+ | Change / delete a role (delete refused once someone checked in; its volunteers are told) | +| POST | `/api/volunteers/manage/roles/:id/assign` | supervisor+ | `{ userId }` — allowed beyond `needed`; the person is told. Audited as `volunteer_assigned` | +| DELETE | `/api/volunteers/manage/slots/:id` | supervisor+ | Take someone off (not after check-in); they're told. Audited as `volunteer_removed` | +| GET | `/api/volunteers/manage/hours?eventId=&from=&to=` | supervisor+ | `[{ userId, name, shifts, hours, events }]` — checked-in shifts × shift length, most first | + ## Webhooks | Method | Path | Auth | Description | diff --git a/apps/events/backend/package-lock.json b/apps/events/backend/package-lock.json index 4b84745..1edc936 100644 --- a/apps/events/backend/package-lock.json +++ b/apps/events/backend/package-lock.json @@ -1,12 +1,12 @@ { "name": "event-management-backend", - "version": "1.45.1", + "version": "1.46.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "event-management-backend", - "version": "1.45.1", + "version": "1.46.0", "hasInstallScript": true, "dependencies": { "@prisma/adapter-pg": "^7.10.1", diff --git a/apps/events/backend/package.json b/apps/events/backend/package.json index 34c0d17..f556311 100644 --- a/apps/events/backend/package.json +++ b/apps/events/backend/package.json @@ -1,6 +1,6 @@ { "name": "event-management-backend", - "version": "1.45.1", + "version": "1.46.0", "description": "Event Management System Backend", "main": "src/index.js", "scripts": { diff --git a/apps/events/backend/prisma/migrations/20261028120000_volunteer_rosters/migration.sql b/apps/events/backend/prisma/migrations/20261028120000_volunteer_rosters/migration.sql new file mode 100644 index 0000000..5f96584 --- /dev/null +++ b/apps/events/backend/prisma/migrations/20261028120000_volunteer_rosters/migration.sql @@ -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; + diff --git a/apps/events/backend/prisma/schema.prisma b/apps/events/backend/prisma/schema.prisma index d3eb927..884d9cd 100644 --- a/apps/events/backend/prisma/schema.prisma +++ b/apps/events/backend/prisma/schema.prisma @@ -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]) +} diff --git a/apps/events/backend/src/controllers/eventController.js b/apps/events/backend/src/controllers/eventController.js index b17ad09..b126b8c 100644 --- a/apps/events/backend/src/controllers/eventController.js +++ b/apps/events/backend/src/controllers/eventController.js @@ -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'); diff --git a/apps/events/backend/src/controllers/registrationController.js b/apps/events/backend/src/controllers/registrationController.js index 48cb959..ff625b4 100644 --- a/apps/events/backend/src/controllers/registrationController.js +++ b/apps/events/backend/src/controllers/registrationController.js @@ -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). diff --git a/apps/events/backend/src/controllers/volunteerController.js b/apps/events/backend/src/controllers/volunteerController.js new file mode 100644 index 0000000..ce2c6f2 --- /dev/null +++ b/apps/events/backend/src/controllers/volunteerController.js @@ -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, +}; diff --git a/apps/events/backend/src/hub/readOnly.js b/apps/events/backend/src/hub/readOnly.js index c2e4cf6..5244497 100644 --- a/apps/events/backend/src/hub/readOnly.js +++ b/apps/events/backend/src/hub/readOnly.js @@ -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) { diff --git a/apps/events/backend/src/index.js b/apps/events/backend/src/index.js index 4d2d648..c5e759c 100644 --- a/apps/events/backend/src/index.js +++ b/apps/events/backend/src/index.js @@ -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:[] }}]}, diff --git a/apps/events/backend/src/jobs/index.js b/apps/events/backend/src/jobs/index.js index e37f800..d16d5d5 100644 --- a/apps/events/backend/src/jobs/index.js +++ b/apps/events/backend/src/jobs/index.js @@ -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 () => { diff --git a/apps/events/backend/src/routes/volunteerRoutes.js b/apps/events/backend/src/routes/volunteerRoutes.js new file mode 100644 index 0000000..fc66a09 --- /dev/null +++ b/apps/events/backend/src/routes/volunteerRoutes.js @@ -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; diff --git a/apps/events/backend/src/utils/accessLog.js b/apps/events/backend/src/utils/accessLog.js index 255f61a..c0dbad1 100644 --- a/apps/events/backend/src/utils/accessLog.js +++ b/apps/events/backend/src/utils/accessLog.js @@ -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', }; /** diff --git a/apps/events/backend/src/utils/campusScope.js b/apps/events/backend/src/utils/campusScope.js index 17b9b1b..69babeb 100644 --- a/apps/events/backend/src/utils/campusScope.js +++ b/apps/events/backend/src/utils/campusScope.js @@ -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. */ diff --git a/apps/events/backend/src/utils/kids.js b/apps/events/backend/src/utils/kids.js index 5932ad4..32110c1 100644 --- a/apps/events/backend/src/utils/kids.js +++ b/apps/events/backend/src/utils/kids.js @@ -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, }; diff --git a/apps/events/backend/src/utils/notifications.js b/apps/events/backend/src/utils/notifications.js index a7d79d1..fba6d68 100644 --- a/apps/events/backend/src/utils/notifications.js +++ b/apps/events/backend/src/utils/notifications.js @@ -1513,6 +1513,7 @@ async function sendAttendeeFormLinkMessage(attendee) { } module.exports = { + getEventNotifyEmails, buildEventNotifyRecipientList, sendAttendeeFormLinkMessage, sendRegistrationEmails, diff --git a/apps/events/backend/src/utils/privacy.js b/apps/events/backend/src/utils/privacy.js index cb9a610..f4f478f 100644 --- a/apps/events/backend/src/utils/privacy.js +++ b/apps/events/backend/src/utils/privacy.js @@ -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) { diff --git a/apps/events/backend/src/utils/volunteers.js b/apps/events/backend/src/utils/volunteers.js new file mode 100644 index 0000000..cbef913 --- /dev/null +++ b/apps/events/backend/src/utils/volunteers.js @@ -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, +}; diff --git a/apps/events/backend/tests/volunteers.test.js b/apps/events/backend/tests/volunteers.test.js new file mode 100644 index 0000000..eabcbb1 --- /dev/null +++ b/apps/events/backend/tests/volunteers.test.js @@ -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)); +}); diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index 679ebe1..34f4113 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -1,6 +1,6 @@ # Handover — where things stand and how to carry on -Last updated: 2026-10-28, after **1.45.1** (and Hub 1.1.0). The plan itself is in +Last updated: 2026-10-28, after **1.46.0** (and Hub 1.1.0). The plan itself is in [ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md). @@ -14,6 +14,7 @@ encrypted settings unreadable or break existing installs. | Version | What | |---------|------| +| 1.46.0 | **Volunteer rosters** (§5): serving roles per event or session, anyone signs up (or supervisors assign), day-before reminders, "can't make it" swaps that happen on accept (notify recipients emailed), self check-in with the event's QR code or by staff, kids-room roles count as leaders on duty, free volunteer ticket off by default, roster sheet and hours served. Also fixes the 1.45.0 kids ticket being offered publicly | | 1.45.1 | Privacy notice (built-in text) and terms of use brought up to date with kids check-in, sessions, certificates, campuses, the Hub heartbeat and where data is stored. Installs with a published notice must publish a new version themselves | | 1.45.0 | **Kids check-in** (§4), fully digital: families/children/authorised adults kept between events (My account → Kids), staff desk with pickup codes and a "write on the sticker" panel, rooms with age ranges and ratios, room screen (on duty, call parent, alerts), check-out by code (wrong code alerts, override with reason), offline desk with reserved codes, attendance through a free kids ticket; 6-month retention rule for children | | 1.44.0 | **Campus-scoped staff** (§12 part 2): Admin → Users "Limit to campuses"; `utils/campusScope.js` on every staff/supervisor route (and owner-or-staff routes), lists filtered, scanner names the other campus, church-wide events view/scan/door-only for scoped staff; route test `tests/campusScopeRoutes.test.js` | @@ -41,13 +42,10 @@ encrypted settings unreadable or break existing installs. ## Next up -1. **Roll out the update requests:** deploy **Hub 1.1.0**, then set "Latest Cross Events release" - to `1.42.0` in Hub → Settings, then update the sites to 1.42.0 (the last update done without a - request). A 1.42.0 site talking to an older Hub shows "The Hub doesn't take update requests yet". -2. **Try `scripts/install.sh` on a test server.** The production Hub key is built in since - 1.42.1, so a fresh install needs no `HUB_PUBLIC_KEY`; existing installs can drop it from `.env`. -3. **1.46.0 — Volunteer rosters** (§5), per campus. Wallet passes (§7) are removed from scope - (2026-10-28), so 1.47.0 is event series & cloning and 1.48.0 outbound webhooks. +Hub 1.1.0 is deployed with update requests rolled out, and `scripts/install.sh` has been tried on +a test server (both done 2026-10-28). + +1. **1.47.0 — Event series & cloning** (§6), then **1.48.0 — outbound webhooks** (§8). ## Working on this repo @@ -254,6 +252,30 @@ encrypted settings unreadable or break existing installs. - e2e: `kids.spec.ts` on the seeded hidden "E2E Kids Church" (set up, parent adds a child, desk checks in, parent sees the code, wrong code then the right one, room alert). +## Where volunteer rosters live (1.46.0) + +- `backend/src/utils/volunteers.js` — everything: shifts (`shiftOf`: the role's own times, else its + session's, else the event's), overlap and check-in-window rules, roles, sign-up / leave / swaps, + the free volunteer place (`givePlace` / `releasePlace`, `VolunteerSlot.registrationId`), QR and + manual check-in (kids-room roles start a `KidsRoomDuty` with `fromRoster`), `rosteredForRooms` + (used by the kids board), messages, the `volunteers` reminder job, hours served, and the privacy + parts (`exportVolunteering`, `forgetVolunteer`). Pure parts tested in `tests/volunteers.test.js`. +- `reservedOptionIds` / `publicOptions` there: the kids and volunteer tickets are left out of public + event pages and refused on public registration (`eventController`, `registrationController`). + **A new staff-only ticket type should be added to `reservedOptionIds`.** +- `controllers/volunteerController.js` + `routes/volunteerRoutes.js` (`/api/volunteers`); campus + resolvers `servingRole` and `volunteerSlot`; sign-ups, new roles and assigning are in `readOnly.js`. +- Swaps: no approval — accepting moves the slot at once (claimed with an `updateMany` on + `status: 'open'` so two people can't both take it); `tellOrganisers` emails + `getEventNotifyEmails(event)` (notify recipients, else the creator), not the registrations inbox. +- The check-in QR holds `SERVE-`; the page encodes it as a URL + (`/serve/check-in?code=…`) so phone cameras open it directly. +- Frontend: `lib/volunteers.ts`, `components/volunteers/{RosterSheet,CheckInQr}.tsx`, pages + `dashboard/supervisor/volunteers` (roles, QR, ticket, hours), `dashboard/staff/volunteers` (the day), + `dashboard/user/serving` (`?event=` opens one event — the shareable sign-up link), `serve/check-in`. +- e2e: `volunteers.spec.ts` on the seeded hidden "E2E Serving Sunday" (role, ticket hidden publicly, + sign-up, cover request, staff take over, QR check-in, roster). + ## Known gaps / follow-ups - WhatsApp STOP only works once someone pastes the webhook URL from Site settings → WhatsApp @@ -275,3 +297,7 @@ encrypted settings unreadable or break existing installs. - Kids check-in: the offline desk is tested at the API level (sync, idempotency, code reservation), not in the browser. A family's two parents share one family; linking a second parent is done at the desk ("parents" endpoint) — there's no invite from My account yet. +- Volunteer rosters: if a volunteer edits their free volunteer registration on the edit page, the + volunteer ticket isn't among the public options, so saving drops it (the backend only refuses + adding or increasing it). Rare; the place is still in the roster, and a supervisor can give a + ticket at the door. Reminders are a single "day before" one (no per-event timing yet). diff --git a/apps/events/docs/ROADMAP-v2.md b/apps/events/docs/ROADMAP-v2.md index f9ca200..f93bd71 100644 --- a/apps/events/docs/ROADMAP-v2.md +++ b/apps/events/docs/ROADMAP-v2.md @@ -32,7 +32,9 @@ per campus, public filter and campus pages, home campus, filters, campus broadca 1.44.0 **campus-scoped staff** shipped (Admin → Users "Limit to campuses", every staff route checked). Wallet passes are removed from scope (2026-10-28), so everything after volunteer rosters moves up by one. 1.45.0 **kids check-in** shipped (fully digital: pickup codes, sticker panel, rooms with -ratios, offline desk). **Next: 1.46.0 Volunteer rosters.** +ratios, offline desk). 1.46.0 **volunteer rosters** shipped (roles per event or session, sign-ups and +assigning, swaps on accept, QR self check-in, kids-room roles on duty, optional volunteer ticket). +**Next: 1.47.0 Event series and cloning.** **Repositories:** @@ -443,7 +445,7 @@ Parents manage their family's children in My account and see pickup codes on the ## 5. Volunteer / serving rosters -Plan who serves where, for an event or each session. +Plan who serves where, for an event or each session. (Shipped in 1.46.0 — decisions below.) - **Serving roles** per event/session: Welcome, Parking, Kids, Sound, Kitchen… with the number of people needed. @@ -950,7 +952,7 @@ income justify the hardware: | 5 | 1.38.0 ✅ 1.39.0 ✅ 1.40.0 ✅ | **POPIA toolkit** (1.38.0: user privacy centre, unsubscribe, WhatsApp STOP, data requests inbox; 1.39.0: privacy notice editor + versions, operator register, consent log, access log; 1.40.0: retention jobs, breach register, children’s-data flags, readiness page) | Main selling point; retention jobs use the job queue | | 6 | 1.41.0 ✅ – 1.42.0 ✅ + Hub 1.0 ✅ – 1.1 ✅ | Install/update scripts, `/health`, licence step in `/setup`, "Connect to Hub", heartbeat, licence states — plus the **Hub** app (separate repo); rename to Cross Events (1.41.3); Request update (1.42.0 / Hub 1.1.0) | Must exist before the first church is sold; Hope Family Church registers as install #1 | | 7 | 1.43.0 ✅ – 1.44.0 ✅ | **Multi-campus**: 1.43.0 campuses (settings, events, public filter and landing pages, home campus, filters, messages, summaries); 1.44.0 campus-scoped staff | Kids rooms and volunteer roles are per campus, so campuses come first; scoping is split out because it's security-heavy | -| 8 | 1.45.0 ✅ – 1.46.0 | Kids check-in, Volunteer rosters | Depend on sessions and campuses | +| 8 | 1.45.0 ✅ – 1.46.0 ✅ | Kids check-in, Volunteer rosters | Depend on sessions and campuses | | 9 | 1.47.0 – 1.48.0 | Event series & cloning, Outbound webhooks (Wallet passes removed from scope) | Smaller, independent wins | | 10 | 1.49.0 – 1.51.0 | Admin dashboard/Ctrl+K/bulk actions, Afrikaans, Accessibility pass | Polish before the big release | | 11 | 1.52.0 | TypeScript backend + OpenAPI + `/api/v2` alongside v1 | The breaking-change groundwork | @@ -1005,6 +1007,7 @@ feature. | — | Updates | Sites show **Request update**, never the deploy command: the request goes to the Hub, which tells Joshua; he updates the server. 1.42.0 / Hub 1.1.0; Multi-campus and everything after moves up by one (2026-10-27) | | — | Wallet passes | **Removed from scope** (2026-10-28); everything after volunteer rosters moves up by one | | — | Kids check-in (1.45.0) | One release. **Fully digital** — no label printers: pickup code on the parent's phone, a "write on the sticker" panel for blank stickers. Staff desk only (no kiosk). Anyone with the pickup code can collect; families list authorised adults without accounts. Child profiles deleted after 6 months without a check-in (2026-10-28) | +| — | Volunteer rosters (1.46.0) | Anyone with an account can volunteer. Roles are per event (or per session) — rosters cover one event/session and never repeat. A swap needs no approval: it happens once someone accepts, and the event's notify recipients are emailed. Volunteers check in by scanning a QR code or are checked in by staff. The free volunteer ticket is off by default and chosen per event. A role linked to a kids room counts its checked-in volunteers as leaders on duty for the room's ratio (2026-10-28) | | — | POPIA: WhatsApp STOP | In 1.38.0, via WAWP's incoming `message` webhook with a secret in the URL (WAWP doesn't sign webhooks) (2026-10-23) | ## Still open diff --git a/apps/events/e2e/fixtures.ts b/apps/events/e2e/fixtures.ts index e80f22d..9cbba29 100644 --- a/apps/events/e2e/fixtures.ts +++ b/apps/events/e2e/fixtures.ts @@ -5,7 +5,7 @@ import path from "path"; export type Role = "admin" | "supervisor" | "staff" | "user"; export type Seed = { users: Record; - events: { free: string; paid: string; course: string; dropIn: string; conference: string; kids: string }; + events: { free: string; paid: string; course: string; dropIn: string; conference: string; kids: string; serving: string }; campuses: Record<"north" | "south", { id: string; slug: string }>; northTicketQr: string; course: { sessions: { id: string; label: string }[]; ticketId: string; qrCode: string }; diff --git a/apps/events/e2e/support/prepare-db.js b/apps/events/e2e/support/prepare-db.js index 8671d7b..87e5757 100644 --- a/apps/events/e2e/support/prepare-db.js +++ b/apps/events/e2e/support/prepare-db.js @@ -88,6 +88,14 @@ async function seed(url) { price: 0, isHidden: true, createdById: users.supervisor.id, }, }); + // Volunteer rosters (volunteers.spec.ts): on today, hidden. + const serving = await prisma.event.create({ + data: { + title: 'E2E Serving Sunday', description: 'Volunteer rosters for the tests.', startDate: new Date(Date.now() - 60 * 60 * 1000), endDate: new Date(Date.now() + 6 * 60 * 60 * 1000), + price: 0, isHidden: true, createdById: users.supervisor.id, + eventOptions: { create: [{ name: 'Entry', price: 0, isMainTicket: true }] }, + }, + }); const paid = await prisma.event.create({ data: { campusId: south.id, @@ -181,7 +189,7 @@ async function seed(url) { const out = { users: Object.fromEntries(Object.entries(users).map(([k, u]) => [k, { id: u.id, name: u.name, email: u.email, token: generateToken(u.id, u.role, u.tokenVersion || 0) }])), - events: { free: free.id, paid: paid.id, course: course.id, dropIn: dropIn.id, conference: conference.id, kids: kids.id }, + events: { free: free.id, paid: paid.id, course: course.id, dropIn: dropIn.id, conference: conference.id, kids: kids.id, serving: serving.id }, campuses: { north: { id: north.id, slug: north.slug }, south: { id: south.id, slug: south.slug } }, northTicketQr: northTicket.qrCode, course: { sessions: course.sessions.map(s => ({ id: s.id, label: s.label })), ticketId: ticket.id, qrCode: ticket.qrCode }, diff --git a/apps/events/e2e/volunteers.spec.ts b/apps/events/e2e/volunteers.spec.ts new file mode 100644 index 0000000..8ab9e73 --- /dev/null +++ b/apps/events/e2e/volunteers.spec.ts @@ -0,0 +1,65 @@ +import { test, expect, seed, loginAs, API } from "./fixtures"; + +// Volunteer rosters (1.46.0): a supervisor adds a role and switches the free volunteer ticket on, +// a user signs up, can't make it and asks for cover, staff take the place over, then check in by +// scanning the event's QR code. "E2E Serving Sunday" is seeded hidden and on today. +test.describe.serial("volunteer rosters", () => { + test("a supervisor adds a role and switches the volunteer ticket on", async ({ page }) => { + await loginAs(page, "supervisor"); + await page.goto(`/dashboard/supervisor/volunteers?event=${seed().events.serving}`); + await page.getByRole("button", { name: "Add a role" }).click(); + await page.getByLabel("Role name").fill("Welcome team"); + await page.getByLabel("People needed").fill("1"); + await page.getByRole("button", { name: "Add role" }).click(); + await expect(page.getByTestId("roster-role")).toContainText("Welcome team"); + await expect(page.getByTestId("roster-totals")).toContainText("0 of 1"); + + await page.getByRole("tab", { name: "Volunteer ticket" }).click(); + await page.getByRole("button", { name: /Add a free "Volunteer" ticket/ }).click(); + await expect(page.getByLabel("Volunteer ticket")).not.toHaveValue(""); + }); + + test("the volunteer ticket isn't offered publicly", async ({ request }) => { + const res = await request.get(`${API}/api/events/${seed().events.serving}`); + const ev = await res.json(); + expect(ev.eventOptions.map((o: { name: string }) => o.name)).toEqual(["Entry"]); + }); + + test("a user signs up, then asks for cover", async ({ page }) => { + await loginAs(page, "user"); + await page.goto(`/dashboard/user/serving?event=${seed().events.serving}`); + await page.getByTestId("open-role").filter({ hasText: "Welcome team" }).getByRole("button", { name: "Sign up" }).click(); + await expect(page.getByRole("status")).toContainText("you're on the roster"); + const shift = page.getByTestId("my-shift").filter({ hasText: "Welcome team" }); + await expect(shift).toContainText("free volunteer ticket"); + + page.once("dialog", d => d.accept("Away that weekend")); + await shift.getByRole("button", { name: "Can't make it" }).click(); + await expect(shift).toContainText("Cover requested"); + }); + + test("staff take the place over, then check in with the QR code", async ({ page, request }) => { + await loginAs(page, "staff"); + await page.goto("/dashboard/user/serving"); + const cover = page.getByTestId("cover-request").filter({ hasText: "Welcome team" }); + await expect(cover).toContainText("Away that weekend"); + await cover.getByRole("button", { name: "Take over" }).click(); + await expect(page.getByRole("status")).toContainText("taken over Welcome team"); + await expect(page.getByTestId("my-shift").filter({ hasText: "Welcome team" })).toBeVisible(); + + // The QR code on the wall holds this; a phone camera opens the check-in page. + const qr = await request.get(`${API}/api/volunteers/manage/events/${seed().events.serving}/qr`, { headers: { Authorization: `Bearer ${seed().users.supervisor.token}` } }); + const { qr: code } = await qr.json(); + await page.goto(`/serve/check-in?code=${encodeURIComponent(code)}`); + await expect(page.getByTestId("volunteer-checked-in")).toContainText("Welcome team"); + }); + + test("the roster shows who took over and checked in", async ({ page }) => { + await loginAs(page, "supervisor"); + await page.goto(`/dashboard/supervisor/volunteers?event=${seed().events.serving}`); + const volunteer = page.getByTestId("roster-volunteer"); + await expect(volunteer).toContainText(seed().users.staff.name); + await expect(volunteer).toContainText("(QR)"); + await expect(page.getByTestId("roster-totals")).toContainText("1 checked in"); + }); +}); diff --git a/apps/events/frontend/package-lock.json b/apps/events/frontend/package-lock.json index dc446be..092e82e 100644 --- a/apps/events/frontend/package-lock.json +++ b/apps/events/frontend/package-lock.json @@ -1,12 +1,12 @@ { "name": "hope-events-frontend", - "version": "1.45.1", + "version": "1.46.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "hope-events-frontend", - "version": "1.45.1", + "version": "1.46.0", "dependencies": { "@dnd-kit/core": "^6.3.1", "@hookform/resolvers": "^5.2.1", diff --git a/apps/events/frontend/package.json b/apps/events/frontend/package.json index 323d5e8..1b9f522 100644 --- a/apps/events/frontend/package.json +++ b/apps/events/frontend/package.json @@ -1,6 +1,6 @@ { "name": "hope-events-frontend", - "version": "1.45.1", + "version": "1.46.0", "private": true, "scripts": { "dev": "next dev --turbopack", diff --git a/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx b/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx index 85bb2cd..4bff067 100644 --- a/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx +++ b/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx @@ -109,6 +109,11 @@ const ACTION_LABELS: Record = { kids_wrong_code: "Wrong pickup code entered", kids_custody_notes_changed: "Child's custody notes changed", kids_offline_sync: "Offline kids desk synced", + volunteer_settings_updated: "Volunteer ticket changed", + volunteer_roles_changed: "Serving role added, changed or deleted", + volunteer_assigned: "Volunteer put on a roster", + volunteer_removed: "Volunteer taken off a roster", + volunteer_checked_in_manual: "Volunteer checked in by hand", }; interface AuditLogEntry { diff --git a/apps/events/frontend/src/app/dashboard/admin/page.tsx b/apps/events/frontend/src/app/dashboard/admin/page.tsx index 92abeb0..d81c11b 100644 --- a/apps/events/frontend/src/app/dashboard/admin/page.tsx +++ b/apps/events/frontend/src/app/dashboard/admin/page.tsx @@ -9,7 +9,7 @@ import { useVisiblePolling } from "@/hooks/useVisiblePolling"; import { Calendar, Banknote, Gift, Users, Ticket, QrCode, ClipboardList, UserPlus, FileText, MessageCircle, BarChart2, Mail, Wallet, DoorOpen, History, TicketPercent, ShieldCheck, ListChecks, WifiOff, BedDouble, Filter, ClipboardCheck, Inbox, - Baby, + Baby, HandHeart, } from "lucide-react"; import { StatCard, StatCardRow } from "@/components/shared/StatCard"; import { QuickActionTile, QuickActionGrid } from "@/components/shared/QuickActionTile"; @@ -33,6 +33,7 @@ const QUICK_ACTIONS = [ { href: "/dashboard/supervisor/allocations", label: "Rooms & groups", description: "Put attendees into rooms, groups or buses", icon: BedDouble }, { href: "/dashboard/staff/kids", label: "Kids check-in", description: "Check children in and out with pickup codes", icon: Baby }, { href: "/dashboard/supervisor/kids", label: "Kids check-in setup", description: "Switch it on for an event and set up the rooms", icon: Baby }, + { href: "/dashboard/supervisor/volunteers", label: "Volunteer rosters", description: "Serving roles, who serves where, check-ins and hours", icon: HandHeart }, { href: "/dashboard/supervisor/offline-scans", label: "Offline scanning", description: "Devices scanning offline and their synced scans", icon: WifiOff }, { href: "/dashboard/supervisor/attendance", label: "Attendance", description: "Who came to each session, and certificates", icon: ClipboardCheck }, { href: "/dashboard/supervisor/waitlist", label: "Waitlist", description: "People waiting for sold-out tickets", icon: ListChecks }, diff --git a/apps/events/frontend/src/app/dashboard/staff/page.tsx b/apps/events/frontend/src/app/dashboard/staff/page.tsx index f87f4a0..600a43b 100644 --- a/apps/events/frontend/src/app/dashboard/staff/page.tsx +++ b/apps/events/frontend/src/app/dashboard/staff/page.tsx @@ -6,7 +6,7 @@ import { useRouter } from "next/navigation"; import { apiFetch } from "@/lib/api"; import { useStableState } from "@/hooks/useStableState"; import { useVisiblePolling } from "@/hooks/useVisiblePolling"; -import { QrCode, Ticket, Activity, UserCheck, Clock, Users, ClipboardCheck, Baby } from "lucide-react"; +import { QrCode, Ticket, Activity, UserCheck, Clock, Users, ClipboardCheck, Baby, HandHeart } from "lucide-react"; import { StatCard, StatCardRow } from "@/components/shared/StatCard"; import { QuickActionTile, QuickActionGrid } from "@/components/shared/QuickActionTile"; import type { DashboardStats, RecentScan, ScanStats } from "@/types"; @@ -17,6 +17,7 @@ const QUICK_ACTIONS = [ { href: "/dashboard/staff/event-tickets", label: "Event tickets & printing", description: "Browse event tickets and print lists", icon: Ticket }, { href: "/dashboard/staff/my-groups", label: "My groups", description: "Rooms and groups you lead", icon: Users }, { href: "/dashboard/staff/kids", label: "Kids check-in", description: "Check children in and out with pickup codes", icon: Baby }, + { href: "/dashboard/staff/volunteers", label: "Volunteers", description: "Who is serving today, check-ins and the check-in QR code", icon: HandHeart }, { href: "/dashboard/supervisor/attendance", label: "Attendance", description: "Who came to each session of an event", icon: ClipboardCheck }, ] as const; diff --git a/apps/events/frontend/src/app/dashboard/staff/volunteers/page.tsx b/apps/events/frontend/src/app/dashboard/staff/volunteers/page.tsx new file mode 100644 index 0000000..eb09cc5 --- /dev/null +++ b/apps/events/frontend/src/app/dashboard/staff/volunteers/page.tsx @@ -0,0 +1,71 @@ +"use client"; + +import React, { useEffect, useState } from "react"; +import { useAuth } from "@/hooks/useAuth"; +import { apiFetch } from "@/lib/api"; +import { errorMessage } from "@/lib/utils"; +import { formatDate } from "@/lib/date"; +import { useDismissingState } from "@/hooks/useDismissingState"; +import { BackLink } from "@/components/shared/BackLink"; +import { RosterSheet } from "@/components/volunteers/RosterSheet"; +import { CheckInQr } from "@/components/volunteers/CheckInQr"; +import { HandHeart } from "lucide-react"; +import type { RosterEvent } from "@/lib/volunteers"; + +/** Staff → Volunteers: the roster on the day — who's here, ticking people in, and the check-in QR code. */ +export default function StaffVolunteersPage() { + const { token } = useAuth(); + const [events, setEvents] = useState(null); + const [eventId, setEventId] = useState(""); + const [showQr, setShowQr] = useState(false); + const [msg, setMsg] = useDismissingState<{ type: "ok" | "err"; text: string } | null>(null); + + useEffect(() => { + if (!token) return; + apiFetch("/api/volunteers/manage/events", { authToken: token }) + .then(list => { + setEvents(list); + const now = Date.now(); + const current = list.find(e => new Date(e.endDate).getTime() >= now); + if (current) setEventId(current.id); + }) + .catch(e => setMsg({ type: "err", text: errorMessage(e) || "Could not load events" })); + }, [token, setMsg]); + + const event = events?.find(e => e.id === eventId); + + return ( +
+
+
+
+ +

Volunteers

+

Who's serving today, and checking them in

+
+
+ + {events && !events.length &&
No events have volunteer rosters yet. A supervisor adds serving roles under Supervisor → Volunteer rosters.
} + {events && events.length > 0 && ( +
+ + {eventId && } +
+ )} + + {msg &&
{msg.text}
} + +
+ {eventId && (showQr + ? + : )} +
+
+ ); +} diff --git a/apps/events/frontend/src/app/dashboard/supervisor/page.tsx b/apps/events/frontend/src/app/dashboard/supervisor/page.tsx index 291dd8b..c0ee847 100644 --- a/apps/events/frontend/src/app/dashboard/supervisor/page.tsx +++ b/apps/events/frontend/src/app/dashboard/supervisor/page.tsx @@ -9,7 +9,7 @@ import { useVisiblePolling } from "@/hooks/useVisiblePolling"; import { Calendar, Banknote, Gift, Users, Ticket, QrCode, DoorOpen, Wallet, UserPlus, FileText, MessageCircle, BarChart2, Mail, TicketPercent, ShieldCheck, ListChecks, WifiOff, BedDouble, Filter, ClipboardCheck, - Baby, + Baby, HandHeart, } from "lucide-react"; import { StatCard, StatCardRow } from "@/components/shared/StatCard"; import { QuickActionTile, QuickActionGrid } from "@/components/shared/QuickActionTile"; @@ -30,6 +30,7 @@ const QUICK_ACTIONS = [ { href: "/dashboard/supervisor/allocations", label: "Rooms & groups", description: "Put attendees into rooms, groups or buses", icon: BedDouble }, { href: "/dashboard/staff/kids", label: "Kids check-in", description: "Check children in and out with pickup codes", icon: Baby }, { href: "/dashboard/supervisor/kids", label: "Kids check-in setup", description: "Switch it on for an event and set up the rooms", icon: Baby }, + { href: "/dashboard/supervisor/volunteers", label: "Volunteer rosters", description: "Serving roles, who serves where, check-ins and hours", icon: HandHeart }, { href: "/dashboard/supervisor/offline-scans", label: "Offline scanning", description: "Devices scanning offline and their synced scans", icon: WifiOff }, { href: "/dashboard/supervisor/attendance", label: "Attendance", description: "Who came to each session, and certificates", icon: ClipboardCheck }, { href: "/dashboard/supervisor/waitlist", label: "Waitlist", description: "People waiting for sold-out tickets", icon: ListChecks }, diff --git a/apps/events/frontend/src/app/dashboard/supervisor/volunteers/page.tsx b/apps/events/frontend/src/app/dashboard/supervisor/volunteers/page.tsx new file mode 100644 index 0000000..d047126 --- /dev/null +++ b/apps/events/frontend/src/app/dashboard/supervisor/volunteers/page.tsx @@ -0,0 +1,154 @@ +"use client"; + +import React, { useCallback, useEffect, useState } from "react"; +import { useAuth } from "@/hooks/useAuth"; +import { apiFetch } from "@/lib/api"; +import { errorMessage } from "@/lib/utils"; +import { formatDate } from "@/lib/date"; +import { useDismissingState } from "@/hooks/useDismissingState"; +import { BackLink } from "@/components/shared/BackLink"; +import { RosterSheet } from "@/components/volunteers/RosterSheet"; +import { CheckInQr } from "@/components/volunteers/CheckInQr"; +import { HandHeart } from "lucide-react"; +import { hoursText, type HoursRow, type RosterEvent } from "@/lib/volunteers"; + +type Settings = { + event: { id: string; title: string; volunteerOptionId: string | null }; + options: { id: string; name: string; price: number }[]; + kidsRooms: { id: string; name: string }[]; +}; +type Tab = "roster" | "qr" | "ticket" | "hours"; +const TABS: { id: Tab; label: string }[] = [ + { id: "roster", label: "Roster" }, + { id: "qr", label: "Check-in QR" }, + { id: "ticket", label: "Volunteer ticket" }, + { id: "hours", label: "Hours served" }, +]; + +/** Supervisor → Volunteer rosters: serving roles per event or session, people, check-in QR, volunteer ticket, hours. */ +export default function VolunteerRostersPage() { + const { token } = useAuth(); + const [events, setEvents] = useState([]); + const [eventId, setEventId] = useState(""); + const [tab, setTab] = useState("roster"); + const [settings, setSettings] = useState(null); + const [hours, setHours] = useState(null); + const [hoursAll, setHoursAll] = useState(true); + const [msg, setMsg] = useDismissingState<{ type: "ok" | "err"; text: string } | null>(null); + const [busy, setBusy] = useState(false); + + useEffect(() => { + if (!token) return; + apiFetch("/api/volunteers/manage/events?all=1", { authToken: token }) + .then(list => { + setEvents(list); + const wanted = new URLSearchParams(window.location.search).get("event"); + if (wanted && list.some(e => e.id === wanted)) setEventId(wanted); + }) + .catch(e => setMsg({ type: "err", text: errorMessage(e) || "Could not load events" })); + }, [token, setMsg]); + + const loadSettings = useCallback(async () => { + if (!token || !eventId) { setSettings(null); return; } + try { + setSettings(await apiFetch(`/api/volunteers/manage/events/${eventId}/settings`, { authToken: token })); + } catch (e) { + setMsg({ type: "err", text: errorMessage(e) || "Could not load the settings" }); + } + }, [token, eventId, setMsg]); + useEffect(() => { loadSettings(); }, [loadSettings]); + + useEffect(() => { + if (!token || tab !== "hours") return; + setHours(null); + apiFetch(`/api/volunteers/manage/hours${!hoursAll && eventId ? `?eventId=${eventId}` : ""}`, { authToken: token }) + .then(setHours) + .catch(e => setMsg({ type: "err", text: errorMessage(e) || "Could not load hours" })); + }, [token, tab, hoursAll, eventId, setMsg]); + + const saveTicket = async (optionId: string | null, ok: string) => { + setBusy(true); + try { + setSettings(await apiFetch(`/api/volunteers/manage/events/${eventId}/settings`, { method: "PUT", authToken: token, body: { optionId } })); + setMsg({ type: "ok", text: ok }); + } catch (e) { + setMsg({ type: "err", text: errorMessage(e) || "Could not save" }); + } finally { + setBusy(false); + } + }; + + const event = events.find(e => e.id === eventId); + + return ( +
+
+
+
+ +

Volunteer rosters

+

Who serves where, for an event or each session

+
+
+ + + + {msg &&
{msg.text}
} + +
+ {TABS.map(t => ( + + ))} +
+ +
+ {tab !== "hours" && !eventId &&

Choose an event.

} + {tab === "roster" && eventId && ( +

+ Sign-up link to share: {`${typeof window !== "undefined" ? window.location.origin : ""}/dashboard/user/serving?event=${eventId}`} +

+ )} + {tab === "roster" && eventId && } + {tab === "qr" && eventId && } + {tab === "ticket" && eventId && settings && ( +
+

Free volunteer ticket

+

Off unless you choose a ticket. When it's on, everyone on this event's roster gets a free place on it (shown in their My Events), unless they already have a ticket. It's never offered to the public, and it's given back when they leave the roster.

+
+ + {!settings.event.volunteerOptionId && } +
+

Places already given stay when you switch it off.

+
+ )} + {tab === "hours" && ( +
+
+ + +
+

Shifts people checked in for, counted at the shift's length.

+ {!hours &&
Loading…
} + {hours && hours.length === 0 &&

No checked-in shifts yet.

} + {hours && hours.length > 0 && ( + + + {hours.map(h => )} +
VolunteerShiftsEventsHours
{h.name}{h.shifts}{h.events}{hoursText(h.hours)}
+ )} +
+ )} +
+
+ ); +} diff --git a/apps/events/frontend/src/app/dashboard/user/serving/page.tsx b/apps/events/frontend/src/app/dashboard/user/serving/page.tsx new file mode 100644 index 0000000..7944e9c --- /dev/null +++ b/apps/events/frontend/src/app/dashboard/user/serving/page.tsx @@ -0,0 +1,186 @@ +"use client"; + +import React, { useCallback, useEffect, useState } from "react"; +import { useAuth } from "@/hooks/useAuth"; +import { apiFetch } from "@/lib/api"; +import { errorMessage } from "@/lib/utils"; +import { formatDate } from "@/lib/date"; +import { useDismissingState } from "@/hooks/useDismissingState"; +import { BackLink } from "@/components/shared/BackLink"; +import { CheckCircle2, HandHeart, QrCode, Repeat } from "lucide-react"; +import type { CoverRequest, MySlot, Roster, ServingEvent } from "@/lib/volunteers"; + +type Mine = { slots: MySlot[]; cover: CoverRequest[]; events: ServingEvent[] }; +type Msg = { type: "ok" | "err"; text: string } | null; + +const btn = "px-3 py-1.5 rounded-lg text-sm border disabled:opacity-50"; + +/** My account → Serving: my shifts, cover requests I could take, and events looking for volunteers. */ +export default function ServingPage() { + const { token } = useAuth(); + const [data, setData] = useState(null); + const [msg, setMsg] = useDismissingState(null); + const [busy, setBusy] = useState(false); + const [openEvent, setOpenEvent] = useState(""); + const [roster, setRoster] = useState(null); + + const load = useCallback(async () => { + if (!token) return; + try { + setData(await apiFetch("/api/volunteers/me", { authToken: token })); + } catch (e) { + setMsg({ type: "err", text: errorMessage(e) || "Could not load your shifts" }); + } + }, [token, setMsg]); + useEffect(() => { load(); }, [load]); + // ?event=: the sign-up link a supervisor shares (works for hidden events too). + useEffect(() => { + const wanted = new URLSearchParams(window.location.search).get("event"); + if (wanted) setOpenEvent(wanted); + }, []); + + const loadRoster = useCallback(async (id: string) => { + if (!token || !id) { setRoster(null); return; } + try { + setRoster(await apiFetch(`/api/volunteers/events/${id}`, { authToken: token })); + } catch (e) { + setMsg({ type: "err", text: errorMessage(e) || "Could not load the roles" }); + } + }, [token, setMsg]); + useEffect(() => { loadRoster(openEvent); }, [openEvent, loadRoster]); + + const call = async (fn: () => Promise, ok: string) => { + setBusy(true); + try { + await fn(); + setMsg({ type: "ok", text: ok }); + await Promise.all([load(), openEvent ? loadRoster(openEvent) : null]); + } catch (e) { + setMsg({ type: "err", text: errorMessage(e) || "Something went wrong" }); + } finally { + setBusy(false); + } + }; + + const askCover = (s: MySlot) => { + const note = prompt(`Ask the other volunteers to take over ${s.role.name}? The first to accept takes your place. Add a note (optional):`, ""); + if (note === null) return; + call(() => apiFetch(`/api/volunteers/slots/${s.slotId}/swap`, { method: "POST", authToken: token, body: { note } }), "Cover requested — you stay on the roster until someone takes over."); + }; + const withdraw = (s: MySlot) => confirm(`Withdraw from ${s.role.name} at ${s.event.title}? The organisers will be told.`) + && call(() => apiFetch(`/api/volunteers/slots/${s.slotId}`, { method: "DELETE", authToken: token }), "You're off the roster for this shift."); + + const upcoming = (data?.slots || []).filter(s => !s.past); + const past = (data?.slots || []).filter(s => s.past); + + return ( +
+
+
+
+ +

Serving

+

Your volunteer shifts, and events looking for people to serve

+
+
+ + {msg &&
{msg.text}
} + {!data &&
Loading…
} + + {data && ( +
+

My shifts

+ {upcoming.length === 0 &&

You're not on any roster yet. Sign up for a role below.

} + {upcoming.map(s => ( +
+
+
+
{s.role.name} · {s.event.title}
+
{s.role.sessionLabel ? `${s.role.sessionLabel} · ` : ""}{s.shift.text}{s.event.location ? ` · ${s.event.location}` : ""}
+ {s.role.kidsRoom &&
Kids room: {s.role.kidsRoom}
} + {s.role.description &&
{s.role.description}
} + {s.hasTicket &&
Your free volunteer ticket is in My Events.
} +
+ {s.checkedInAt + ? Checked in + : s.swapId && Cover requested} +
+ {s.canCheckIn &&

When you arrive, scan the volunteer check-in QR code with your phone's camera.

} + {!s.checkedInAt && ( +
+ {s.swapId + ? + : } + +
+ )} +
+ ))} + {past.length > 0 && ( +
+ Last week ({past.length}) +
    + {past.map(s =>
  • {s.role.name} · {s.event.title} · {s.shift.text}{s.checkedInAt ? " · served" : ""}
  • )} +
+
+ )} +
+ )} + + {data && data.cover.length > 0 && ( +
+

Can you take over?

+ {data.cover.map(c => ( +
+
+
{c.role.name} · {c.event.title}
+
{c.role.sessionLabel ? `${c.role.sessionLabel} · ` : ""}{c.shift.text}
+
{c.from || "A volunteer"} can't make it{c.note ? `: “${c.note}”` : ""}
+
+ +
+ ))} +
+ )} + + {data && ( +
+

Serve at an event

+ {data.events.length === 0 && !openEvent &&

No events are looking for volunteers right now.

} + {(data.events.length > 0 || openEvent) && ( + + )} + {roster && roster.event.id === openEvent && ( +
+ {roster.roles.filter(r => !r.past).map(r => ( +
+
+
{r.name}{r.kidsRoom ? · kids room {r.kidsRoom.name} : null}
+
{r.sessionLabel ? `${r.sessionLabel} · ` : ""}{r.shift.text}
+ {r.description &&
{r.description}
} +
{r.filled} of {r.needed} signed up
+
+ {r.mine + ? You're serving + : r.coverNeeded.length > 0 + ? + : r.full + ? Full + : } +
+ ))} + {roster.roles.every(r => r.past) &&

All shifts at this event are over.

} +
+ )} +
+ )} +
+ ); +} diff --git a/apps/events/frontend/src/app/serve/check-in/page.tsx b/apps/events/frontend/src/app/serve/check-in/page.tsx new file mode 100644 index 0000000..27c287d --- /dev/null +++ b/apps/events/frontend/src/app/serve/check-in/page.tsx @@ -0,0 +1,74 @@ +"use client"; + +import React, { Suspense, useEffect, useRef, useState } from "react"; +import Link from "next/link"; +import { useSearchParams } from "next/navigation"; +import { Navbar } from "@/components/layout/Navbar"; +import { Footer } from "@/components/layout/Footer"; +import { useAuth } from "@/hooks/useAuth"; +import { apiFetch } from "@/lib/api"; +import { errorMessage } from "@/lib/utils"; +import { CheckCircle2, HandHeart } from "lucide-react"; + +type Result = { event: { id: string; title: string }; checkedIn: { role: string; kidsRoom: string | null }[]; already: string[] }; + +/** Where the volunteer check-in QR code leads: checks the signed-in volunteer in for today's shifts. */ +function CheckIn() { + const code = useSearchParams().get("code") || ""; + const { user, token, loading } = useAuth(); + const [result, setResult] = useState(null); + const [error, setError] = useState(code ? null : "This check-in link is incomplete — scan the QR code again."); + const sent = useRef(false); + + useEffect(() => { + if (!code || loading || !token || sent.current) return; + sent.current = true; + apiFetch("/api/volunteers/check-in", { method: "POST", authToken: token, body: { qr: code } }) + .then(setResult) + .catch(e => setError(errorMessage(e) || "Couldn't check you in.")); + }, [code, loading, token]); + + if (error) return
{error} My shifts
; + if (loading) return
Loading…
; + if (!user) { + const back = `/serve/check-in?code=${encodeURIComponent(code)}`; + return ( +
+

Log in to check in for your volunteer shift.

+ Log in +
+ ); + } + if (!result) return
Checking you in…
; + return ( +
+
Thank you for serving, {user.name?.split(" ")[0]}!
+

You're checked in at {result.event.title}:

+
    + {result.checkedIn.map(c =>
  • {c.role}{c.kidsRoom ? ` — you're on duty in ${c.kidsRoom}` : ""}
  • )} + {result.already.map(r =>
  • {r} (already checked in)
  • )} +
+ My shifts +
+ ); +} + +export default function VolunteerCheckInPage() { + return ( +
+ +
+
+
+ +
+

Volunteer check-in

+
+ Loading…
}> + + + +