alumni_lookup

Phase 21 Launch Guide — Alumni Opportunities

Phase spec: phases/phase-21/README.md Scope: alumnichampions.com signup ecosystem (Public::) + Signup Admin. Does not touch belmontalum.com / Cp::. Build order: 21.1 → 21.5 → 21.4 → 21.2 → 21.3 (CMS and staff visibility both ship before the public form) Status: ✅ All five sub-phases built and merged 2026-07-27. This guide is now the deploy + QA checklist, not a plan.

Design change 2026-07-27: opportunity definitions are DB-backed with an admin CMS, not config/opportunities.yml. See §2c of the spec. This guide reflects the CMS design.

Update this guide as you build. Every migration, rake task, and placeholder URL gets added here the moment it’s created.

---

1. Pre-Deployment: Migrations

#	Migration	Sub-phase	Risk	Notes
1	CreateOpportunities	21.1	🟢 Low	✅ Written. New table. Unique index on slug, plus an index on active. fields jsonb default [] not null; active boolean default false not null. Includes activated_at — the slug lock keys off it, not active (spec §3).
2	CreateOpportunityResponses	21.1	🟢 Low	✅ Written. New table. Indexes: opportunity_slug, district_id, champion_signup_id, created_at. FKs to districts and champion_signups are nullable.
3	AddReviewedAtToOpportunityResponses	21.4	🟢 Low	✅ Written. Adds nullable reviewed_at + index to a table that is empty until 21.2 goes live. Read/unread for the sidebar badge only — not a fulfillment state.
4	AddSignupLinkMethodToOpportunityResponses	21.6	🟢 Low	✅ Written. Adds nullable signup_link_method + index, and backfills existing linked rows from source (opportunity_hub → verified, else email_match). No rows exist in production yet, so the backfill is belt-and-braces.
5	AddListedAndNotifyEmailsToOpportunities	21.7	🟢 Low	✅ Written. Adds listed (boolean, default true, not null) and notify_emails (text, nullable) to opportunities, plus a partial index on (active, listed) WHERE active AND listed. Both defaults reproduce current behavior exactly: every existing opportunity stays listed, and a null notify_emails sends no mail. No backfill step.

6	AddEventDetailsToOpportunities	21.8	🟢 Low	✅ Written. Adds starts_at, ends_at, when_note, location, ask_text (all nullable) and send_receipt_email (boolean, default false, not null) to opportunities, plus an index on starts_at. Every default reproduces current behavior: an undated opportunity never expires, and a receipt is sent only where staff tick the box. No backfill — see §4.
7	RemoveWhenNoteFromOpportunities	21.9	🟡 Low-medium	✅ Written. Drops when_note, added one release earlier in migration 6 — an undated opportunity now derives “Ongoing” instead. This is a column drop: old dynos calling when_note during the release window will raise. The window is seconds on this app, and the column is ~one release old, so any data in it is a few staff keystrokes. If staff have used it in earnest, back it up first.

Migrations 5 and 6 add columns to opportunities (21.7, 21.8); migrations 1–4 add no columns to any pre-existing table. champion_signups is untouched throughout — per §7 of the spec, new concepts get their own identity-agnostic tables rather than new columns on champion_signups.

Rollback: rails db:rollback STEP=6 unwinds all six cleanly. No data dependency in either direction until 21.2 goes live. Rolling back only migration 6 (STEP=1) is safe on a live system only if no opportunity has been given a date — it drops six columns and with them the expiry behavior, so a dated opportunity that was 404ing becomes reachable again. Rolling back 5 and 6 together (STEP=2) reverts opportunities to “all listed, no email”, the pre-21.7 behavior.

---

2. Pre-Deployment: Rake Tasks

None required. No backfill exists to run — both tables start empty, and the four opportunities are authored through the CMS rather than seeded (§2c).

Staging → production promotion of opportunity content is the one manual step. Options, in order of preference:

1. Re-enter through the CMS on production (~10 min for Admissions Fair, then Duplicate for the rest). Simplest, no tooling, and it re-verifies the editor in prod.
2. rake opportunities:export[slug] / opportunities:import — a small JSON round-trip task. Build this only if re-entry proves annoying; it is not in scope by default.

Do not copy rows between databases by hand — slug uniqueness and the frozen field keys must stay coherent.

---

3. Content Needing Staff Verification

Item	Where	Needed before
Admissions Fair copy (intro_md, thankyou_md, next_steps_md) + the 4 essay questions	CMS → /champion_signups/opportunities	21.2 public launch
Watch Party / Speaking / Send-Off	CMS (via Duplicate + edit)	Only when each is activated
Privacy policy version string	consent capture	21.2 — must match the value 19.11 writes to champion_signups.privacy_policy_version

Only Admissions Fair should be active at launch. The other three stay inactive (404 publicly) until staff author their copy. Because active is a DB boolean toggled from the CMS, this is now a click rather than a deploy.

---

4. Content Dependencies

The feature is inert without staff action — there is no public index page by design, so an opportunity only gets traffic when staff share its deep link:

https://alumnichampions.com/opportunities/admissions_fair

Before announcing:

• Admissions Fair copy authored and reviewed against LANGUAGE_STYLE_GUIDE.md
• Copy leads with “alumni” / “Bruins” — no gatekeeping language (external-facing rule)
• Staff know where responses land (Signup Admin → Opportunities → Responses)
• Staff know notifications are in-app + push only by default — email is per-opportunity opt-in (21.7 staff list, 21.8 alum receipt)

21.8 — move the event details out of the intro copy. There is deliberately no automated backfill: parsing free-form markdown on live copy is guesswork, and there is one opportunity to fix. After deploy:

• Open Almost Alumni Breakfast in the CMS
• Move the When: / Where: / The ask: lines from Intro into the new Event details fields, and delete them from the intro — otherwise the page shows both
• Preview and confirm each fact appears exactly once
• Decide whether to set real dates. Setting them closes the form after the event, which is usually what you want; leaving them blank keeps today’s behavior
• Decide whether to tick Email the person who signed up — recommended for anything with a date

---

5. Sensitive Features / QA Focus Areas

5a. Anonymous access boundary (highest risk in this phase)

The single most important behavior to verify. Submitting an opportunity form with someone else’s email must never grant access to that person’s record.

• Submit admissions_fair anonymously using the email of an existing ChampionSignup
• Thank-you page copy is byte-identical to the copy shown for a brand-new email — no name echo, no “welcome back”, no account confirmation
• Thank-you page contains no link into /sign-up/:id or /profile/:code
• The profile link arrives only by email, at the address on file
• Response record is linked (champion_signup_id set) even though the page revealed nothing
• Repeat with a non-matching email: same page, and the emailed follow-up is the signup invite rather than a profile link

5b. Consent capture (mirrors 19.11)

• Form cannot be submitted without the consent checkbox
• privacy_policy_accepted_at and privacy_policy_version are written on every response
• Version string matches what the signup flow writes
• Privacy policy link resolves on the alumnichampions.com domain (it serves its own — see config/routes.rb:52)

5c. Spam / rate limiting

• Honeypot trip returns the same success redirect as a real submission (silent fake success), no record created
• 6th submission from one IP inside 30 minutes is throttled (mirrors champion-signups/ip)
• Throttle does not fire on the staff admin side or on GET of the form

5d. Location derivation

• Valid zip → city, state, district_id all populated from ZipCode.lookup
• Staff list shows city, state — not the metro district name (regression guard for 55dd1bf3)
• Unknown/invalid zip → record still saves, location fields nil, no exception

5e. Config-driven rendering

• Unknown slug → 404
• Inactive opportunity → 404 (not a blank form)
• Markdown in intro_md / thankyou_md / next_steps_md renders through OpportunityMarkdown (not Cp::WelcomeContentGenerator — see 21.5 deviation 1 in the spec; that renderer does not sanitize)
• Staff-authored markdown cannot inject script — paste <script>alert(1)</script>, <img src=x onerror=alert(1)>, and [x](javascript:alert(1)) into intro_md; confirm all three appear as inert visible text with no live element and no anchor. Covered by test/services/opportunity_markdown_test.rb, but verify once in a real browser
• select rejects a value not in its options when posted directly (server-side, not just the <select>)
• Missing required field → re-render with errors, no data loss on the other fields
• Field marked inactive stops rendering publicly but its prior answers still appear in the staff view and CSV

5h. CMS (21.5) — the new surface

• Full CRUD round-trip: create with several field rows, save, reopen — field order, types, labels, and required flags all survive
• Key freeze: edit a field’s label after responses exist → the underlying key does not change and prior answers still resolve
• Soft delete: removing a field marks it inactive rather than dropping it; answers are retained
• Slug lock: slug is editable on a draft, locked once activated or once responses exist
• Warning banner appears when editing an opportunity that has responses
• destroy is blocked when responses exist; deactivate is offered instead
• select row requires at least one option before save
• Exactly one contact_block enforced — can’t save zero or two
• Preview renders the real public form without publishing, and does not create a response
• Duplicate: copy is inactive, has a fresh unique slug, regenerated field keys, copied markdown, and zero responses; original is untouched
• Activate / deactivate take effect immediately on the public URL — no deploy
• ensure_portal_admin! guard: a staff-only user cannot reach the CMS (it now lives at /champion_signups/opportunities — the guard is declared on the controller, not inherited)
• The old /champions/opportunities path is gone (404) and no longer appears in the Champions sidebar
• Mobile/responsive check on the field-row editor (the densest new UI in the phase)

5f. Staff surface (21.4)

• Opportunities section appears in the Signup Admin sidebar between Signups and Analytics, with Opportunities (portal_admin only) and Responses
• A staff-only user sees Responses but not the editor link
• Responses badge counts unreviewed, not total — open one and confirm the badge drops by one
• Filters work: opportunity, district, on-file vs. new, review state, date range; sorts newest/oldest/name/location
• Location column reads city, state — never the metro district name (commit 55dd1bf3)
• Opening a response stamps reviewed_at; reloading does not move it; Mark unreviewed puts it back in the badge
• Detail view shows answers to retired questions, labeled as such
• Detail view links to the ChampionSignup when one is linked, and says “new name to us” when not
• StaffNotification type opportunity_response fires in-app and push, no email
• Export button is hidden until an opportunity is selected; hitting export_csv without one redirects with an explanatory alert
• CSV columns: one per question in field order, retired ones marked (retired), and BOTH buid and contact_id when the linked signup has a BUID (data rule)
• Export honors the filters currently applied to the list
• Mobile/responsive check — the Signup Admin list is card-based on small screens (19.11/19.12 pattern)

5i. Public form + thank-you (21.2 / 21.6) — verify by hand once

• The thank-you page names the opportunity and shows the “What you sent us” receipt with the answers just submitted
• Anonymous, email does NOT match: “Want to make it official?” + “Already signed up with us?”, no greeting by name
• Anonymous, email DOES match an existing signup: page is visually identical to the previous case — no greeting, no hub link
• Neither anonymous version links into /sign-up/:id
• Arrived from the hub (token): greeted by first name, Back to your profile button works, and the two anonymous CTAs are gone
• Opening /opportunities/:slug/thank-you directly in a fresh browser shows the anonymous version, never the personalized one
• “Email me a link” on the thank-you page reaches the 19.7 flow and behaves generically for an unknown address
• Reloading the thank-you page does not create a second response
• Rate limit: six rapid submissions from one IP → the sixth is throttled

5j. Profile hub (21.3 / 21.6)

• “Ways to show up” lists active opportunities only, and the section disappears entirely when none are live
• Following a hub link pre-fills the contact block and the resulting response has champion_signup_id set, source: opportunity_hub, and signup_link_method: verified
• opportunity_viewed / opportunity_submitted appear in the signup’s Activity timeline
• Layout: two columns at ≥1024px (main = opportunities + sections, sidebar = details + team), one column below that
• Adaptive lead: a signup missing a section leads with “About you”; one with all three leads with “Ways to show up” and shows “All set — thank you!”
• A signup with no ZIP shows the amber prompt full-width under the header, above both columns
• Mobile check at 375×667 — nothing overflows, the email in the details card wraps rather than pushing the card wide

5k. Identity confidence (21.6) — the distinction staff act on

• Response submitted from the hub shows Confirmed — same person (green) in the staff detail view
• Response submitted anonymously with a matching email shows Likely — matched on email (amber) and the “don’t treat it as confirmed” caution
• Response with no match shows New to us
• The “Who responded” filter separates Confirmed — signed in from Likely — matched on email
• CSV signup_match column reads confirmed / email_match / blank to match

5l. Checkbox fields, link-only visibility, notification email (21.7)

Checkbox questions

• CMS → add a question → type Checkboxes (pick any). The choices box appears; save with choices empty and confirm it’s refused.
• Preview renders the checkboxes disabled and unsubmittable.
• Public form: tick two boxes, submit, and confirm the staff detail view shows them comma-joined and the CSV shows them semicolon-joined.
• Mark the question required, submit with nothing ticked, and confirm the form comes back with an error rather than saving. (This is the exact bug found while building it — an empty array read as “not blank”.)
• Retire a checkbox question and confirm past answers still show in the staff view and the export.

Link-only visibility

• Set an opportunity to Link only and go live. Its direct URL works; it is absent from a returning alum’s profile hub.
• Switch it off. The direct URL now 404s — listed never overrides active.
• Confirm the index and show pages carry the amber Link only badge, and that it does not appear on an opportunity that is switched off.

Notification email — the one to verify carefully, since it is the reversal of 21.4’s no-email rule

• Leave notify_emails blank, submit a response, and confirm no email is sent and the admin in-app notification still arrives. This is the default state of every existing opportunity and the whole safety mechanism.
• Enter a malformed address and confirm the CMS refuses to save it.
• Enter two real addresses, submit a response, and confirm both receive it, that they are bcc’d (neither sees the other), and that reply addresses the submitter.
• Submit as an anonymous alum → email says “new name to us”.
• Submit from a profile-token link as a signup with a matched BUID → email shows grad year, location, affinities, and degrees, labeled confirmed.
• Submit anonymously using the email address of an existing signup → email shows the record but labeled unconfirmed. Verify this wording explicitly; it is what stops staff acting on a guess as if it were proof.
• Staff queue link in the email points at alumnilookup.com, not alumnichampions.com.
• Put an address with no Lookup Portal account on the list and confirm that email has no staff-queue link (it would only reach a login screen).
• Put a portal user and an outsider on the same list, submit once, and confirm two emails go out — the portal user’s with the link, the outsider’s without.
• Read one email on a phone. Questions and answers stack; nothing runs off the right edge. (A long staff-authored question pushed the answers off the page in the first cut — worth re-checking against the real questions on your longest form.)
• “What we already know” shows grad year + degrees (and industry/job/affinities if set) — and not location, district, signup date, BUID or BQID. Those are in the CSV export instead; confirm the CSV still has buid and contact_id.

Print / Save as PDF (21.7)

• Open a response → Print / PDF opens a new tab with no sidebar or navbar.
• ⌘P → the print preview shows a clean document: no toolbar, no back link, sensible margins, and no question separated from its answer across a page break.
• Save as PDF and open the file — everything the email contains is present and readable.
• Link a previously-anonymous response to a Champion, then reprint: the PDF shows the newly linked record. (This is the point of it being live rather than a copy of the email.)
• Print an email-matched response and confirm the unconfirmed match caveat is on the page — a forwarded PDF must carry it.
• Printing does not change the response’s reviewed state or the sidebar badge count.

---

5m. Event details, expiry, and the receipt email (21.8)

Display

• An opportunity with all three fields blank shows no details block at all — no empty card, no “TBD”. (This is every opportunity authored before 21.8.)
• Filling only one field shows only that row, with its label
• The details render identically on the public form and the staff Preview
• The thank-you page repeats them under The details
• A hub opportunity card shows When · Where; an opportunity with neither falls back to the question count
• An opportunity with no dates reads “Ongoing” on the form, the thank-you page, and in both emails
• “Ongoing” does not appear on a hub card — that’s the group heading’s job

Expiry — the highest-risk part of 21.8

• Set a start date of today and confirm the form is reachable all day, including after the start time
• Set a start date of yesterday and confirm the public link 404s and the opportunity leaves the profile hub
• For a range, confirm it expires on the end date, not the start
• Submit while live, then expire it, then reload the thank-you page — the receipt must still render. This is the case that breaks if thank_you ever picks up the expiry filter
• The staff detail, edit, and index screens badge it Ended rather than Live, and the preview banner explains the 404
• An expired opportunity is still openable and editable in the CMS
• Changing the date on an expired opportunity reopens the public link
• An undated opportunity is unaffected by all of the above

Hub ordering

• With two live opportunities, the dated one sorts above the undated one whatever the titles are
• Two dated opportunities sort soonest-first

Receipt email (opt-in)

• With the box unticked, submitting sends the submitter nothing (staff notifications still fire)
• With it ticked, the submitter receives one email; the staff list still receives theirs
• The receipt comes from alumni@, not noreply@, and replying reaches a human
• It contains the details, the thank-you and next-steps copy, and their own answers
• A checkbox answer renders comma-separated, not run together
• The plain-text part has no markdown syntax in it
• Submit as a known Champion and confirm the email contains no profile link and no token — this is the anonymous boundary, and a misdirected copy must disclose nothing but what the sender typed

---

5n. Event styling, grouping, and the venue split (21.9)

Hub grouping

• With one dated and one undated opportunity live, the hub shows Upcoming events above Ongoing opportunities
• With only one kind live, neither heading appears — it looks like it did before the split
• Dated cards carry a blue date bar (SEP / 30); undated cards have none
• A multi-day range shows a + under the day
• Dated opportunities sort soonest-first above the undated ones

Cards

• A dated card does not repeat the date beside the bar — only the time
• An undated card does not print “Ongoing”
• A card with no date and no place still falls back to “N quick questions — we already have your details.”

Venue / address split — the reason to test on real content

• Type the venue on line 1 and the address beneath it: venue renders bold, address smaller underneath, View Map appears and opens the right place
• Type a one-line location (“Various locations”): renders bold, no address line, no View Map
• A stray blank line between venue and address doesn’t shift the address into the venue slot

Ongoing

• An opportunity with no dates reads Ongoing on the form, the thank-you page, the staff preview, and both emails
• The staff detail page also says “Ongoing” — staff read the same word alumni do
• The CMS Where field explains the first-line-is-venue rule, and the date box explains both states (dated = event that closes, blank = ongoing)
• There is no “When — say it differently” field anywhere in the CMS

Mobile (375px)

• The date bar doesn’t squeeze the title into two characters per line
• A long venue + address wraps without pushing “Count me in” off-screen

---

5g. Conversion loop

• “Make it official” carries the contact block into the Phase 19 signup flow, pre-filled
• Completing signup stamps opportunity_response.champion_signup_id
• Signed opportunity_response_id token cannot be tampered with to claim a different response

---

6. Sub-Phase Deployment Stages

Stage	Sub-phase	Independently deployable?	Public impact
1	21.1 Data model	✅ Yes	None — two empty tables, nothing routed
2	21.5 Opportunity CMS	✅ Yes	None — staff-only. Content authoring happens here
3	21.4 Staff management	✅ Yes	None — staff-only surface, empty list
4	21.2 Public pages	✅ Yes	Live. First point at which anonymous PII is captured
5	21.3 Profile-hub integration	✅ Yes	Adds the hub section for returning signups

Stages 1–3 are zero-risk deploys — nothing is publicly reachable, because active defaults to false and no public route exists until stage 4. Stage 4 is the real launch gate; do not deploy it until §5a, §5b, and §5h pass on staging.

Kill switch (built): OPPORTUNITIES_ENABLED=false darks the whole feature — public pages 404 and the hub section disappears — via Opportunity.publicly_available. Unset defaults to on, so it can never dark the feature by omission. The per-opportunity active toggle in the CMS remains the primary control; the env var exists only for an emergency global off.

---

7. Post-Deployment Verification

# Only admissions_fair should be active at launch
echo 'Opportunity.active.pluck(:slug)' | bin/rails console

# Field definitions survived the CMS round-trip
echo 'Opportunity.find_by(slug: "admissions_fair").fields.map { |f| f.values_at("key", "type", "required") }' | bin/rails console

# After the first real submission
echo 'OpportunityResponse.last.slice(:opportunity_slug, :city, :state, :district_id, :champion_signup_id, :privacy_policy_accepted_at)' | bin/rails console

# Notification fan-out reached staff
echo 'StaffNotification.for_type("opportunity_response").count' | bin/rails console

# Unreviewed count — this is what the sidebar badge shows
echo 'OpportunityResponse.unreviewed.count' | bin/rails console

# Kill switch is OFF (feature on) in this environment
echo 'Opportunity.feature_enabled?' | bin/rails console

# Confidence split on linked responses — email matches should NOT read as confirmed
echo 'OpportunityResponse.group(:signup_link_method).count' | bin/rails console

# Active opportunity renders
curl -sI https://alumnichampions.com/opportunities/admissions_fair | head -1   # 200

# Inactive and unknown slugs both 404
curl -sI https://alumnichampions.com/opportunities/watch_party | head -1       # 404
curl -sI https://alumnichampions.com/opportunities/not_a_thing | head -1       # 404

# Must NOT be reachable on the portal domain
curl -sI https://belmontalum.com/opportunities/admissions_fair | head -1       # 404

---

7b. Staging Content Authoring (the editor’s acceptance test)

Still outstanding. Do this on staging before activating anything in production:

1. Author Admissions Fair end to end through /champion_signups/opportunities — contact block + the 4 essay questions + all three markdown blocks. Building it through the real editor is the acceptance test for the editor.
2. Duplicate it three times and edit into Watch Party / Speaking / Send-Off.
3. Activate only Admissions Fair.
4. Promote to production by re-entering through the CMS (§2) — do not copy rows between databases.

---

8. Rollback Plan

Situation	Action
Copy is wrong / opportunity launched early	Deactivate from the CMS — instant, no deploy. Slug 404s immediately; captured responses are retained. Fix the copy and reactivate.
Feature-wide problem	OPPORTUNITIES_ENABLED=false on Heroku — no deploy needed.
Spam flood despite throttle	Tighten the rack-attack limit (config change + deploy), or deactivate the opportunity (instant). If notifications are the problem, that’s the trigger to build the deferred batching (§5 of the spec).
Schema problem	rails db:rollback STEP=4 unwinds to before the phase. Only safe before real responses exist — after launch, export via Csv::OpportunityResponseExporter first.
Staff broke a live form by editing fields	The §2c rules make this largely non-destructive by construction: keys are frozen, deletes are soft, and the slug is locked. Reactivate the field or restore the label; answers were never lost.
Staff deleted an opportunity	destroy is blocked once responses exist. A no-response opportunity that’s deleted is genuinely gone — recreate it, or Duplicate from a similar one.

---

9. Convergence Guardrail Check (§7 of the spec)

Before wrapping the phase, confirm the reconciliation-safety rules held:

• Opportunity and OpportunityResponse live at app/models/ — not under public/ or cp/
• No Cp:: controller, view, or route was added. Both staff controllers live in ChampionSignups:: (Signup Admin) — the signup ecosystem’s own shell, not a belmontalum.com surface
• No new column was added to champion_signups
• Nothing in this phase lets a ChampionSignup holder see other people — bearer links stay scoped to a person’s own record