From 1a58b3db1a4ce365717d2d930c384c24e0121b3a Mon Sep 17 00:00:00 2001 From: Matt Date: Wed, 29 Apr 2026 02:06:28 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20design=20spec=20for=20PR=206=20?= =?UTF-8?q?=E2=80=94=20lunch=20event?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Locked-in design covering data model (LunchEvent, Dish, MemberLunchPick, ExternalAttendee + DietaryTag/Allergen enums), tRPC API surface, admin/team-lead/member UI on Logistics → Lunch tab and applicant dashboard, reminder + recap email/cron flows, edge cases, and testing strategy. Ready for implementation plan. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../2026-04-29-pr6-lunch-event-design.md | 348 ++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-29-pr6-lunch-event-design.md diff --git a/docs/superpowers/specs/2026-04-29-pr6-lunch-event-design.md b/docs/superpowers/specs/2026-04-29-pr6-lunch-event-design.md new file mode 100644 index 0000000..81649bf --- /dev/null +++ b/docs/superpowers/specs/2026-04-29-pr6-lunch-event-design.md @@ -0,0 +1,348 @@ +# PR 6 — Lunch event (design) + +Date: 2026-04-29 +Status: design locked, ready for implementation plan + +## 1. Goal & scope + +Replace the Lunch tab placeholder on `/admin/logistics` with a working flow: admins configure a single per-edition lunch event, attendees pick a dish + log allergies, and the manifest is reviewable in-app, exportable to CSV, and emailed at the change deadline. + +**In scope:** + +- New models: `LunchEvent` (1:1 per program), `Dish` (per event), `MemberLunchPick` (1:1 per `AttendingMember`), `ExternalAttendee` (per program, optionally team-attached). +- Enums: `DietaryTag`, `Allergen`. +- Admin UI on the existing Logistics → Lunch tab: event config card, dishes CRUD, manifest table, externals CRUD, recap preview/send, audit logging. +- Team-lead UX: dish/allergy editing for any `AttendingMember` on their project, on the existing applicant dashboard. +- Member self-serve UX: dish/allergy editing for own `AttendingMember`, on the same dashboard. +- Single reminder email (configurable hours before deadline). +- Recap email (manual button + cron auto-send, both toggleable; admin recipients + free-form extras). +- Removal of the Lunch placeholders from Edition settings and from the disabled Logistics tab trigger. + +**Out of scope:** + +- No caterer-facing email integration. Admins forward the recap manually. +- No multi-event per edition (1:1 with `Program`). +- No public token-gated picker. Members must have an account; team leads or admins fill in for non-active members. +- Editable email templates (lands in PR 7). + +## 2. Permission matrix + +| Editor | Can edit | +| --- | --- | +| Member (logged in) | Their own dish + allergies, until deadline | +| Team lead | Any `AttendingMember` on their project, until deadline | +| Admin | Everything — all `AttendingMember` picks + all `ExternalAttendee` records, no deadline cap | + +External (off-platform) attendees are admin-only to manage; team leads see them on the project page read-only when an external is attached to their team. + +*"Team lead"* throughout this spec means a user with a `TeamMember` row on the project where `TeamMember.role === 'LEAD'` (existing enum value, defined at `schema.prisma:273-277`). + +*"Admins of the edition"* (used by recap recipients and audit-log actor scoping) means all users with `role === 'SUPER_ADMIN'` plus all users with `role === 'PROGRAM_ADMIN'`. There is no per-program admin scoping today, so all program admins receive the recap. + +## 3. Data model + +```prisma +enum DietaryTag { + VEGETARIAN + VEGAN + GLUTEN_FREE + PESCATARIAN +} + +enum Allergen { + GLUTEN // cereals containing gluten + CRUSTACEANS + EGGS + FISH + PEANUTS + SOYBEANS + MILK + TREE_NUTS + CELERY + MUSTARD + SESAME + SULPHITES + LUPIN + MOLLUSCS +} + +model LunchEvent { + id String @id @default(cuid()) + programId String @unique // 1:1 — one lunch per edition + enabled Boolean @default(false) + eventAt DateTime? // nullable until admin sets it + endAt DateTime? + venue String? + notes String? @db.Text + changeCutoffHours Int @default(48) + reminderHoursBeforeDeadline Int? // null = no reminder + cronEnabled Boolean @default(true) // auto-recap at deadline + extraRecipients String[] @default([]) // off-platform recap recipients + reminderSentAt DateTime? // cron idempotency + recapSentAt DateTime? // gates "send updated recap?" prompt + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + program Program @relation(fields: [programId], references: [id], onDelete: Cascade) + dishes Dish[] + externalAttendees ExternalAttendee[] +} + +model Dish { + id String @id @default(cuid()) + lunchEventId String + name String + sortOrder Int @default(0) + dietaryTags DietaryTag[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + lunchEvent LunchEvent @relation(fields: [lunchEventId], references: [id], onDelete: Cascade) + memberPicks MemberLunchPick[] + externals ExternalAttendee[] + + @@index([lunchEventId]) +} + +model MemberLunchPick { + id String @id @default(cuid()) + attendingMemberId String @unique // 1:1, mirrors FlightDetail/VisaApplication + dishId String? // null = not picked yet + allergens Allergen[] @default([]) + allergenOther String? // "other" free-text + pickedAt DateTime? // null until first pick made + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + attendingMember AttendingMember @relation(fields: [attendingMemberId], references: [id], onDelete: Cascade) + dish Dish? @relation(fields: [dishId], references: [id], onDelete: SetNull) + + @@index([dishId]) +} + +model ExternalAttendee { + id String @id @default(cuid()) + lunchEventId String + projectId String? // optional — null = standalone (jury/dignitary/etc.) + name String + email String? + roleNote String? + dishId String? + allergens Allergen[] @default([]) + allergenOther String? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + lunchEvent LunchEvent @relation(fields: [lunchEventId], references: [id], onDelete: Cascade) + project Project? @relation(fields: [projectId], references: [id], onDelete: SetNull) + dish Dish? @relation(fields: [dishId], references: [id], onDelete: SetNull) + + @@index([lunchEventId]) + @@index([projectId]) +} +``` + +**Back-references on existing models:** + +```prisma +model Program { + // ...existing fields... + lunchEvent LunchEvent? +} + +model AttendingMember { + // ...existing fields... + lunchPick MemberLunchPick? +} + +model Project { + // ...existing fields... + externalLunchAttendees ExternalAttendee[] +} +``` + +**Auto-create hook.** When an `AttendingMember` is created, if a `LunchEvent` exists for the parent program, also create an empty `MemberLunchPick` (`dishId=null`, `pickedAt=null`). When the `AttendingMember` is deleted, the cascade handles the pick. Mirrors the visa-application auto-sync added in commit `bdfd998`. + +**Migrations are additive.** Nothing existing changes shape. `pickedAt` is set on the first `upsertPick` call where `dishId` is non-null; subsequent edits update `updatedAt` only. + +## 4. API surface + +New router `src/server/routers/lunch.ts`, mounted as `trpc.lunch.*`. Logistics router unchanged. + +### Admin-only (`adminProcedure`) + +| Procedure | Purpose | +| --- | --- | +| `getEvent` | Get-or-create the `LunchEvent` for the current program (lazy create, mirrors hotel's pattern). | +| `updateEvent` | Patch any subset of: `enabled, eventAt, endAt, venue, notes, changeCutoffHours, reminderHoursBeforeDeadline, cronEnabled, extraRecipients[]`. | +| `createDish` / `updateDish` / `deleteDish` / `reorderDishes` | Dish CRUD. Delete sets `dishId=null` on picks via Prisma `SetNull`. | +| `listExternals` / `createExternal` / `updateExternal` / `deleteExternal` | External-attendee CRUD. | +| `getManifest` | Full manifest: attending members (filtered to `FinalistConfirmation.status === CONFIRMED`) + externals, each with project, name, dish, allergens. Backs the Lunch tab table and CSV export. | +| `exportManifestCsv` | Server-side CSV generation; returns string for client-side download. | +| `getRecapPreview` | Returns the recap email payload (counts + table) for in-app preview. | +| `sendRecap` | Manual send. Input `{ forceUpdate?: boolean }`. If `recapSentAt` is set and `forceUpdate=false`, throws `PRECONDITION_FAILED` so the UI can show the "send updated?" confirm. Sends to admins of the edition + `extraRecipients[]`. Updates `recapSentAt`. Audit-logged. | + +### Mixed permission (`protectedProcedure` with role guard inside) + +| Procedure | Purpose | +| --- | --- | +| `upsertPick` | Single procedure for member-self / team-lead / admin. Input: `{ attendingMemberId, dishId, allergens, allergenOther }`. Guard: caller is (a) the `AttendingMember.userId`, OR (b) team lead of the parent project, OR (c) admin. After `changeCutoffHours` cutoff, only admins pass. Audit-logged on every write with actor role. | + +### Member read (`protectedProcedure`) + +| Procedure | Purpose | +| --- | --- | +| `getEventForMember` | Public-ish event view: `{ enabled, eventAt, endAt, venue, notes, changeDeadline }` for the dashboard banner. Returns `null` when `enabled=false`. | +| `getTeamPicks` | All picks for the caller's team (resolved via `TeamMember → project`). Returns `[{ attendingMemberId, memberName, dish, allergens, hasPicked }]` for the team-wide-read visibility. | + +### Cron endpoints (REST, `CRON_SECRET` guarded) + +| Endpoint | Behavior | +| --- | --- | +| `POST /api/cron/lunch-reminders` | Single fire per event: scans enabled `LunchEvent`s with `reminderHoursBeforeDeadline` set and `reminderSentAt` null. If `now ∈ [reminderAt, deadline)`, emails attending members with `pickedAt=null` whose parent `FinalistConfirmation.status === CONFIRMED`, then stamps `reminderSentAt`. Idempotent. | +| `POST /api/cron/lunch-recap` | Single fire per event: scans enabled `LunchEvent`s with `cronEnabled=true`, `recapSentAt` null, and `now >= deadline`. Sends recap to admins + `extraRecipients[]`, stamps `recapSentAt`. Idempotent. | + +Both endpoints follow the CLAUDE.md rule "Round notifications never throw — all errors caught and logged" with per-event `try/catch` so one failure does not poison the sweep. + +## 5. UI + +### Admin: `/admin/logistics → Lunch tab` + +Stack of cards on the existing tab content area: + +1. **Event config card** — enabled toggle (master switch), `eventAt` + `endAt` date pickers, `venue`, `notes`, `changeCutoffHours`, `reminderHoursBeforeDeadline`, `cronEnabled`, `extraRecipients[]` (chip-input for emails). Same blur-to-commit pattern used by the Edition settings tab. +2. **Dishes card** — list of dishes (name, dietary-tag pills, drag handle for `sortOrder`), inline add row, edit/delete buttons. Empty state: *"Add at least one dish to open picks."* +3. **Manifest card** — table: `Team | Attendee | Type (member/external) | Dish | Allergens | Picked at`. Filters: team dropdown, "Missing picks only" toggle. Header summary chip: *"23/30 picked · 3 vegan · 2 nut-allergic · 1 missing"*. Externals appear inline (team column shows "—" for standalone). Edit-pencil opens a slide-over on any row (admin override). +4. **Externals card** — table of external attendees with add button → dialog (name, email, project (optional), `roleNote`, `dishId`, `allergens`, `allergenOther`). Edits use the same dialog. +5. **Recap actions card** — two buttons: *"Preview recap"* (modal showing email body) and *"Send recap now"* (with the post-deadline "you already sent — resend updated?" confirm); plus *"Download CSV"*. Footer text: *"Last sent: 2026-06-25 14:02. Recipients: 4 admins + 2 extra."* + +When `enabled=false`, cards 2–5 collapse to a single empty state: *"Lunch is disabled — toggle on to configure."* + +### Applicant dashboard (`/applicant`) — extend `AttendingMembersCard` + +Each attending-member row (already shows visa + flight) gets a new collapsible **Lunch** subsection: + +- Dish dropdown (grouped by dietary tag — *"Vegetarian options"*, *"All options"*). +- Allergen checklist (EU 14 inline grid) + "other" textarea. +- "Picked" chip with timestamp once `pickedAt` is set. + +Edit affordance: + +- **Member viewing own row:** editable until deadline. +- **Team lead viewing teammates' rows:** editable until deadline, with a clear *"Editing on behalf of [Name]"* label. +- **Past deadline:** read-only, with note *"Past change deadline. Contact an admin for changes."* + +Above `AttendingMembersCard`, a thin **lunch banner** (only when `enabled=true`) shows event date/time, venue, change-deadline countdown, and a *"Notes from organizers"* expander. + +### Project page + +Read-only **External attendees for your team** strip — only when externals with `projectId === thisProject` exist, so the team knows who's joining them. No edits — admin-only. + +### Removals + +- Drop the Lunch line from the "Coming soon" card on `edition-settings-tab.tsx:212-216`. +- Remove `disabled` from the Lunch tab trigger in `logistics/page.tsx:55-58` and wire it to a new `` component. + +## 6. Email + cron details + +**Email templates** live inline in `src/lib/email.ts` (the existing single-file pattern); no new infrastructure. + +**Reminder.** Subject: *"Pick your lunch dish — deadline in [Xh]"*. Body: greeting, event date/venue/notes, deadline timestamp, button → applicant dashboard. Sent only to attending members with `pickedAt=null` whose confirmation is `CONFIRMED`. + +**Recap.** Subject: *"Lunch manifest — [event date]"*. Body: aggregate counts (dishes, dietary tags, allergens), per-attendee table grouped by team (externals as a final group), event metadata. Plain HTML; no CSV attachment in v1 — admins use the in-app *"Download CSV"* button when needed. + +**Time formatting.** Same approach as the confirmation page: format with `Intl.DateTimeFormat` in the recipient's email-client locale, plus a hardcoded `"Europe/Monaco"` zone label and the ISO timestamp for unambiguous parsing. + +**Audit log entries** (new `eventType` string literals on the existing `DecisionAuditLog.eventType` field — no schema change since the column is free-form): + +- `LUNCH_EVENT_UPDATED` +- `LUNCH_DISH_CREATED` / `LUNCH_DISH_UPDATED` / `LUNCH_DISH_DELETED` +- `LUNCH_PICK_UPDATED` (records actor role: `SELF` / `TEAM_LEAD` / `ADMIN`) +- `LUNCH_EXTERNAL_CREATED` / `LUNCH_EXTERNAL_UPDATED` / `LUNCH_EXTERNAL_DELETED` +- `LUNCH_RECAP_SENT` (with recipient count) + +## 7. Edge cases & error handling + +| Case | Behavior | +| --- | --- | +| `LunchEvent` does not yet exist for the program | `getEvent` lazily creates it with defaults; member/team-lead reads return `null` (banner hidden). | +| Admin disables lunch after picks made | Picks remain in the database; UI hides them; recap still works if re-enabled. | +| `FinalistConfirmation` flips from `CONFIRMED` to `SUPERSEDED` after a pick was made | Pick row stays; manifest filters the team out. If the team is later re-promoted via waitlist, picks are visible again. | +| Dish is deleted | `dishId` becomes `null` on picks/externals; rows show as "not picked"; admins re-pick. Audit logged. | +| `eventAt` is moved | Deadline (`eventAt - changeCutoffHours`) and reminder window recalculate automatically — no manual adjustment needed. | +| `eventAt` is set in the past | Admin sees a UI warning; cron treats deadline as already-past (so a manual send is the only recourse, since `recapSentAt` may already be moot). | +| `changeCutoffHours = 0` | Deadline equals `eventAt`. Allowed. | +| Admin edits a pick after `recapSentAt` is set | UI surfaces a confirm dialog: *"This will not auto-resend the recap. Send updated recap?"* ─ "Yes" calls `sendRecap` with `forceUpdate=true`. Audit logged regardless. | +| Member with no `AttendingMember` row | Cannot edit. UI hides the lunch subsection (no row exists). | +| External with `projectId` that points to a project no longer in the edition | `onDelete: SetNull` on the relation already covers cascades; standalone-display fallback. | + +## 8. Testing strategy + +Vitest, sequential pool (per CLAUDE.md). Tests grouped by router/service: + +**`tests/lunch/lunch-router.test.ts`** + +- `getEvent` lazily creates the row on first call. +- `updateEvent` patches an arbitrary subset. +- Dish CRUD (`createDish`, `updateDish`, `deleteDish`, `reorderDishes`) — delete sets `dishId=null` on existing picks. +- External CRUD covers the standalone (`projectId=null`) and team-attached cases. +- `getManifest` filters out non-`CONFIRMED` confirmations and merges externals. + +**`tests/lunch/upsert-pick.test.ts`** + +- Member edits own row: succeeds before deadline, fails after. +- Team lead edits teammate row: succeeds before deadline, fails after. +- Team lead edits a non-team member's row: fails with `FORBIDDEN`. +- Admin edits any row before/after deadline: succeeds in both cases. +- Audit log records actor role correctly per case. + +**`tests/lunch/recap.test.ts`** + +- `sendRecap` with `recapSentAt=null` succeeds and stamps the timestamp. +- `sendRecap` with `recapSentAt` set and `forceUpdate=false` throws `PRECONDITION_FAILED`. +- `sendRecap` with `forceUpdate=true` succeeds and re-stamps. +- Recap aggregation is correct (dish counts, dietary-tag counts, allergen counts). + +**`tests/lunch/cron.test.ts`** + +- `lunch-reminders` is idempotent (second call within window does not double-send). +- `lunch-reminders` skips events with `reminderSentAt` already set. +- `lunch-recap` skips events with `cronEnabled=false`. +- `lunch-recap` skips events with `recapSentAt` already set. +- Per-event try/catch — a failing send for one event does not stop the next from being processed. + +**`tests/lunch/auto-create.test.ts`** + +- Creating an `AttendingMember` while a `LunchEvent` exists also creates an empty `MemberLunchPick`. +- Creating an `AttendingMember` while no `LunchEvent` exists does not error and does not create a pick. + +Build (`npm run build`), typecheck (`npm run typecheck`), and full test suite must be green before commit. + +## 9. File-level work surface (informative — drives the implementation plan) + +- `prisma/schema.prisma` — add models, enums, back-references; new migration. +- `src/server/routers/lunch.ts` (new) — router as designed. +- `src/server/routers/_app.ts` — mount `lunch` router. +- `src/server/services/lunch-pick-sync.ts` (new) — `ensureLunchPickForAttendingMember` helper called from existing attendee-creation paths. +- `src/server/services/lunch-recap.ts` (new) — manifest aggregation + email body builder, used by `sendRecap` and the recap cron. +- `src/lib/email.ts` — append two new template functions (reminder + recap). +- `src/app/api/cron/lunch-reminders/route.ts` (new). +- `src/app/api/cron/lunch-recap/route.ts` (new). +- `src/app/(admin)/admin/logistics/page.tsx` — un-disable the Lunch tab trigger; mount new tab content. +- `src/components/admin/logistics/lunch-tab.tsx` (new) — orchestrates the five cards. +- `src/components/admin/logistics/lunch-event-config.tsx` (new) — config card. +- `src/components/admin/logistics/lunch-dishes.tsx` (new) — dishes card. +- `src/components/admin/logistics/lunch-manifest.tsx` (new) — manifest card. +- `src/components/admin/logistics/lunch-externals.tsx` (new) — externals card. +- `src/components/admin/logistics/lunch-recap-actions.tsx` (new) — recap actions card. +- `src/components/applicant/attending-members-card.tsx` — extend each row with the lunch subsection. +- `src/components/applicant/lunch-banner.tsx` (new) — the dashboard banner above the attending-members card. +- `src/components/admin/settings/edition-settings-tab.tsx` — drop the Lunch line from the "Coming soon" card. + +## 10. Non-goals reminder + +- No keyboard shortcuts anywhere — visible UI affordances only (per existing user feedback memory). +- No editable email templates in this PR (PR 7). +- No public token-gated picker. +- No multi-event support. +- No caterer email integration.