From 116a2ce4b4ada1fd265cfa3ab5386878bd2d1ed9 Mon Sep 17 00:00:00 2001 From: Joshua Oosthuizen Date: Tue, 27 Oct 2026 17:52:11 +0200 Subject: [PATCH] Campus-scoped staff: help, docs, changelog (1.44.0) Co-Authored-By: Claude Opus 5.5 --- apps/events/CHANGELOG.md | 22 +++++++++++++++ apps/events/FEATURES.md | 9 +++++- apps/events/backend/API_DOCUMENTATION.md | 11 ++++++++ apps/events/backend/package-lock.json | 4 +-- apps/events/backend/package.json | 2 +- apps/events/backend/src/index.js | 4 +-- apps/events/docs/HANDOVER.md | 28 +++++++++++++++---- apps/events/docs/ROADMAP-v2.md | 7 +++-- apps/events/frontend/package-lock.json | 4 +-- apps/events/frontend/package.json | 2 +- .../content/help/dashboard-admin-users.tsx | 5 +++- .../src/content/help/site-settings.tsx | 5 +++- apps/events/package-lock.json | 4 +-- apps/events/package.json | 2 +- 14 files changed, 87 insertions(+), 22 deletions(-) diff --git a/apps/events/CHANGELOG.md b/apps/events/CHANGELOG.md index d1aa16e..2a0b85d 100644 --- a/apps/events/CHANGELOG.md +++ b/apps/events/CHANGELOG.md @@ -7,6 +7,28 @@ and this project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] +## [1.44.0] - 2026-10-27 + +### Added + +- **Staff for some campuses** (Admin → Users → "Limit to campuses", while campuses are on). A + supervisor or staff member limited to some campuses sees only those campuses' events plus + events for all campuses — in every list, report, dashboard, the scanner and offline scanning. + - **Events for all campuses:** they can scan, register people and take payments at the door, but + not change them, cash them up or refund them (the event editor opens read-only). + - **New events** go at one of their campuses; they can't move events to another campus. + - **Admins and supervisors for every campus only:** the site banner, payment reconciliation and + open online checkouts, and donations not linked to an event. + - **Messages:** broadcasts only to people at their campuses or attendees of their events (no + typed-in addresses). **Coupons:** only for their campuses' events. + - Another campus's records answer "not found"; the **scanner says which campus** a ticket is + for. Staff still see their own registrations for any campus's event. + - Their dashboard says which campuses they work with. Admins are never limited, and limits are + ignored while campuses are off (the Campuses tab warns first). Changing someone's limits is in + the audit log; a campus with staff limited to it can't be deleted. + - Every staff and supervisor route declares how it handles campus limits, and a test fails on + any that doesn't (`tests/campusScopeRoutes.test.js`). + ## [1.43.0] - 2026-10-27 ### Added diff --git a/apps/events/FEATURES.md b/apps/events/FEATURES.md index f223db0..bd29c4d 100644 --- a/apps/events/FEATURES.md +++ b/apps/events/FEATURES.md @@ -543,7 +543,14 @@ default — single-campus churches never see campus fields). - **Daily summary:** campus recipients get the summary of their campus's events. - **Turning it off** hides everything campus-related; nothing is deleted. A campus with events can't be deleted, only archived. -- Campus-scoped staff (limited to some campuses) come in 1.44.0. +- **Staff for some campuses** (Admin → Users → "Limit to campuses"): a supervisor or staff member + sees only their campuses' events plus events for all campuses — every list, report, dashboard + and scanner follows it. For church-wide events they can scan, register people and take payments + at the door, but not change, cash up or refund them. The site banner, payment reconciliation and + donations not linked to an event are for admins and unscoped supervisors; broadcasts only reach + people at their campuses or their events' attendees; coupons only for their campuses' events. + Another campus's records answer "not found"; the scanner says which campus a ticket is for. + Admins are never limited; limits are ignored while campuses are off. --- diff --git a/apps/events/backend/API_DOCUMENTATION.md b/apps/events/backend/API_DOCUMENTATION.md index 76c2129..0f3c70c 100644 --- a/apps/events/backend/API_DOCUMENTATION.md +++ b/apps/events/backend/API_DOCUMENTATION.md @@ -868,6 +868,17 @@ below is ignored and `GET /api/campuses` returns `{ enabled: false, campuses: [] | DELETE | `/api/campuses/:id` | admin | Only without events — otherwise `409 CAMPUS_HAS_EVENTS` (archive instead) | | GET | `/api/campuses/:id/audience` | supervisor+ | `{ campus, users }` — home campus, plus `?registrants=true` people registered for its events in the last 12 months (not cancelled). Broadcasts send to these ids as usual, so news consent still applies | +**Campus-scoped staff (1.44.0):** a supervisor or staff member with campus limits +(`PUT /api/users/:id { scopedCampusIds }`, admin; `GET /api/users/:id` returns `scopedCampuses`; +`GET /api/users/profile` returns `campusScope`, null when unscoped or campuses are off) only sees +their campuses' events plus church-wide ones on every staff/supervisor endpoint +(`src/utils/campusScope.js`). Responses for out-of-scope records: +- `404 { message: "Not found" }` — another campus's event or record (nothing leaks). +- `403 { code: "OTHER_CAMPUS" }` — the scanner (`/api/tickets/scan-preview|qr|scan/:qrCode`), naming the ticket's campus. +- `403 { code: "CHURCH_WIDE_EVENT" }` — changing, cashing up or refunding an event for all campuses. +- `403 { code: "CAMPUS_SCOPED" }` — banner, payment reconciliation, open checkouts, unlinked donations, typed-in broadcast addresses or recipients outside their campuses. +- `409 { code: "CAMPUS_HAS_SCOPED_STAFF" }` on `DELETE /api/campuses/:id` while staff are limited to it. + **Campus on other endpoints:** - Events carry `campusId` (null = all campuses) and `campus { id, name, slug, colour }`. `POST`/`PUT /api/events` take `campusId` (`''`/`null` = all campuses; an archived campus can stay but can't be newly chosen); moving an event is audited as `event_campus_changed`. - `GET /api/events?campus=` — that campus's events plus church-wide ones. `GET /api/events/all?campus=` — one campus, or church-wide only. diff --git a/apps/events/backend/package-lock.json b/apps/events/backend/package-lock.json index eac7a4e..6440e17 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.43.0", + "version": "1.44.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "event-management-backend", - "version": "1.43.0", + "version": "1.44.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 63399a9..451bdbf 100644 --- a/apps/events/backend/package.json +++ b/apps/events/backend/package.json @@ -1,6 +1,6 @@ { "name": "event-management-backend", - "version": "1.43.0", + "version": "1.44.0", "description": "Event Management System Backend", "main": "src/index.js", "scripts": { diff --git a/apps/events/backend/src/index.js b/apps/events/backend/src/index.js index 9d39d90..ac01e6d 100644 --- a/apps/events/backend/src/index.js +++ b/apps/events/backend/src/index.js @@ -518,13 +518,13 @@ app.get('/docs', async (req, res) => { responses:[ { status:200, desc:'Success', body:{ exists:true, hasEmail:true, hasPhone:false }}, ]}, - { method:'GET', path:'/api/users/:id', auth:'admin', desc:'Get a single user by ID', + { method:'GET', path:'/api/users/:id', auth:'admin', desc:'Get a single user by ID (with scopedCampuses)', pathParams:{ ':id':'User UUID' }, responses:[ { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', isActive:true, phoneNumber:'+27821234567', notificationPreference:'email' }}, { status:404, desc:'Not found', body:{ message:'User not found' }}, ]}, - { method:'PUT', path:'/api/users/:id', auth:'admin', desc:'Update any user (including role)', + { method:'PUT', path:'/api/users/:id', auth:'admin', desc:'Update any user (including role). scopedCampusIds limits a supervisor/staff member to those campuses (empty = every campus; audited)', pathParams:{ ':id':'User UUID' }, request:{ body:{ role:'supervisor', isActive:true, name:'Jane Doe' }}, responses:[ diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index 10b2ed9..5b79d58 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-27, after **1.43.0** (and Hub 1.1.0). The plan itself is in +Last updated: 2026-10-27, after **1.44.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.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` | | 1.43.0 | **Campuses** (§12 part 1): Site settings → Campuses (off by default), events per campus or all campuses, public campus filter (remembered, starts on home campus) and `/campus/` pages, home campus on the profile, campus filters on Reports and the dashboards, "Everyone at a campus" in broadcasts, campus summary recipients, campus on ticket PDFs, heartbeat `campusCount`. Also adds the `hub_update_requested` audit action missing since 1.42.0 | | 1.42.1 | Production Hub public key built in (`publicKey.js`); `HUB_PUBLIC_KEY` only needed for a local Hub | | 1.42.0 | **Request update** instead of the deploy command: Site settings → Licence sends a signed update request to the Hub (protocol §3a), which opens an alert and emails Joshua; "Update requested on …" until the site runs that version, and the admin update banner hides meanwhile. Audit action `hub_update_requested`. Needs Hub 1.1.0 | @@ -43,10 +44,7 @@ encrypted settings unreadable or break existing installs. 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.44.0 — Campus-scoped staff** (§12, "Plumbing (1.44.0)"): `UserCampusScope`, a - `utils/campusScope.js` helper on every staff/supervisor endpoint (115 in 27 route files at - 1.42.1), and the route-list test that fails on any endpoint that isn't campus-checked or marked - campus-independent. +3. **1.45.0 — Kids check-in** (§4), then 1.46.0 volunteer rosters (§5) — both per campus. ## Working on this repo @@ -212,6 +210,26 @@ encrypted settings unreadable or break existing installs. - e2e: the campuses and two events' campuses are **seeded** in `e2e/support/prepare-db.js` with campuses off (so a pre-built frontend already has them); `campuses.spec.ts` turns them on and off. +## Campus-scoped staff (1.44.0) — adding a staff route + +- **Every route behind `staff` or `supervisor` must carry a marker from `utils/campusScope.js`**, or + `tests/campusScopeRoutes.test.js` fails: + - `scopeEvent({ resolve, from, need, ownerOk, nameCampus })` — one event, or a record traced to + one (`RESOLVERS`: registration, ticket, ticketQr, payment, eventOption, optionVariant, bundle, + allocationSet/Group, waitlistEntry, scanLock, syncReport, section, certificate, consentRequest). + `need: 'manage'` for setup, cashup and refunds (church-wide events refused). + - `scopeBody([[field, resolver], …], { need, orphan })` — records named in the body (lists of ids + too); `orphan: 'deny'` when there must be an event (payments). + - `scopeList` — the controller filters with `listWhere(req, path)` / `withScope(where, extra)` + (never spread a scope `where` over one that has its own OR) or checks itself. + - `unscopedOnly`, `campusIndependent('reason')`, `scopeBroadcast({ freeformField })`. +- Routes open to the owner *and* staff (no role middleware, so the test can't see them) need + `scopeEvent({ …, ownerOk: true })` by hand — registrations, payments, tickets, consent requests + and coupon validation have it. +- Rules: admins never scoped; scopes ignored while campuses are off; another campus → 404, except + the scanner (403 naming the campus). Tested in `tests/campusScope.test.js` and e2e + `campus-scoped.spec.ts` (staff and supervisor scoped to E2E South; a seeded North ticket). + ## Known gaps / follow-ups - WhatsApp STOP only works once someone pastes the webhook URL from Site settings → WhatsApp diff --git a/apps/events/docs/ROADMAP-v2.md b/apps/events/docs/ROADMAP-v2.md index a55c463..e418562 100644 --- a/apps/events/docs/ROADMAP-v2.md +++ b/apps/events/docs/ROADMAP-v2.md @@ -28,8 +28,9 @@ Cross Events Hub); 1.42.0 **Request update** button instead of the deploy comman (update requests); 1.42.1 the production Hub key built in. Later versions moved up by one (2026-10-27). Multi-campus is split in two — 1.43.0 campuses, 1.44.0 campus-scoped staff — so everything after moves up by one more (2026-10-27). 1.43.0 **campuses** shipped (settings, events -per campus, public filter and campus pages, home campus, filters, campus broadcasts and summaries). -**Next: 1.44.0 Campus-scoped staff.** +per campus, public filter and campus pages, home campus, filters, campus broadcasts and summaries); +1.44.0 **campus-scoped staff** shipped (Admin → Users "Limit to campuses", every staff route checked). +**Next: 1.45.0 Kids check-in.** **Repositories:** @@ -932,7 +933,7 @@ income justify the hardware: | 4 | 1.36.0 ✅ – 1.37.2 | Payment provider interface (Yoco moved behind it) → PayFast, then hiding "Pay online" when it can't be used and payment status checks (SnapScan and Zapper dropped) | Payment code gets split out of the big controller as part of this | | 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 | +| 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 | | 9 | 1.47.0 – 1.49.0 | Event series & cloning, Wallet passes, Outbound webhooks | Smaller, independent wins | | 10 | 1.50.0 – 1.52.0 | Admin dashboard/Ctrl+K/bulk actions, Afrikaans, Accessibility pass | Polish before the big release | diff --git a/apps/events/frontend/package-lock.json b/apps/events/frontend/package-lock.json index 713e62e..ddbdb1a 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.43.0", + "version": "1.44.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "hope-events-frontend", - "version": "1.43.0", + "version": "1.44.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 bbf9cf6..71429fc 100644 --- a/apps/events/frontend/package.json +++ b/apps/events/frontend/package.json @@ -1,6 +1,6 @@ { "name": "hope-events-frontend", - "version": "1.43.0", + "version": "1.44.0", "private": true, "scripts": { "dev": "next dev --turbopack", diff --git a/apps/events/frontend/src/content/help/dashboard-admin-users.tsx b/apps/events/frontend/src/content/help/dashboard-admin-users.tsx index fee3828..e22e729 100644 --- a/apps/events/frontend/src/content/help/dashboard-admin-users.tsx +++ b/apps/events/frontend/src/content/help/dashboard-admin-users.tsx @@ -1,5 +1,5 @@ import React from "react"; -import { Users, UserPlus, ShieldAlert, Eye } from "lucide-react"; +import { Users, UserPlus, ShieldAlert, Eye, MapPinned } from "lucide-react"; import { GuideItem } from "@/components/shared/GuideItem"; import type { HelpContent } from "./types"; @@ -19,6 +19,9 @@ export const dashboardAdminUsersHelpContent: HelpContent = { Click a row to open the edit modal — you can change name, email, role, phone, notification preference, active status, or set a new password. + + With campuses on (Site settings → Campuses), a supervisor or staff member can be limited to some campuses. They then see only those campuses' events plus events for all campuses: they can scan, register people and take payments for church-wide events, but not change them, cash them up or refund them. They also can't use the site banner or payment reconciliation, and only message people at their campuses. Leave every box empty for someone who works with every campus. Admins are never limited, and limits are ignored while campuses are off. + ), diff --git a/apps/events/frontend/src/content/help/site-settings.tsx b/apps/events/frontend/src/content/help/site-settings.tsx index 6a82a86..77dbdae 100644 --- a/apps/events/frontend/src/content/help/site-settings.tsx +++ b/apps/events/frontend/src/content/help/site-settings.tsx @@ -50,7 +50,10 @@ export const siteSettingsHelpContent: HelpContent = { People can choose a home campus on their profile. In Email and WhatsApp broadcasts, Everyone at a campus adds the people whose home campus it is — and, ticked, people who registered for its events in the last 12 months. News still only goes to people who opted in. - A campus with events can't be deleted — archive it instead: it disappears from filters and new events, and its events keep it. Turning campuses off hides everything campus-related; nothing is deleted, and it all comes back when you turn them on again. + A campus with events — or with staff limited to it — can't be deleted; archive it instead: it disappears from filters and new events, and its events keep it. Turning campuses off hides everything campus-related, and staff limits are ignored while off; nothing is deleted, and it all comes back when you turn them on again. + + + In Admin → Users, a supervisor or staff member can be limited to some campuses — they then only work with those campuses' events and events for all campuses. See the Users help for what they can and can't do. diff --git a/apps/events/package-lock.json b/apps/events/package-lock.json index 58834ae..497b654 100644 --- a/apps/events/package-lock.json +++ b/apps/events/package-lock.json @@ -1,12 +1,12 @@ { "name": "hope-events", - "version": "1.43.0", + "version": "1.44.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "hope-events", - "version": "1.43.0", + "version": "1.44.0", "license": "ISC", "devDependencies": { "@playwright/test": "^1.64.0", diff --git a/apps/events/package.json b/apps/events/package.json index 4a17afb..bcdb51d 100644 --- a/apps/events/package.json +++ b/apps/events/package.json @@ -1,6 +1,6 @@ { "name": "hope-events", - "version": "1.43.0", + "version": "1.44.0", "main": "index.js", "scripts": { "dev:backend": "cd backend && npm run dev",