alumni_lookup

Phase 19.9 — Signup Admin Dashboard, District Translation, Spam Guard

Status: Released as v1.0.67 (2026-07-09; interview complete same day; user approved proceeding without model handoff switch) Parent: Phase 19 README

Overview

With Champion Signup re-elevated and the Alumni Network de-elevated, this sub-phase:

1. Unifies the Champion Signup email signature
2. Translates signup zip codes into District/Region (persisted, backfilled)
3. Adds a district location filter to the signups index
4. Adds a honeypot spam guard to the public signup flow
5. Builds a new sidebar-based Champion Signups admin dashboard at /champion_signups and restructures the navbar dropdown around it

No new tables. One new column on champion_signups.

Decisions (from planning interview, 2026-07-09)

Question	Decision
Signature scope	Champion Signup mailer emails only (welcome, profile link, admin notification). Portal Devise emails unchanged.
Honeypot behavior	Silent fake success — hand-rolled hidden field + minimum-time trap, no gem. Bot sees normal success; no record, no email.
Dashboard home	Own sidebar section at /champion_signups (new dashboard root). ChampionSignup queries stay out of champions/ (Cp::) namespace.
Navbar dropdown	Alumni Network removed from dropdown entirely. Dropdown section becomes “Champion Signups” (Dashboard, Insights). Alumni Network admin reachable via link in the new signup sidebar.
Top locations widget	Top districts (not regions), per user preference.

1. Email Signature

• welcome_email.html.erb / .text.erb: “The Alumni Team” → “The Belmont Alumni Engagement Team”
• profile_link_email.*: already correct — verify both formats
• admin_notification.*: internal; add/normalize signature to match
• Extract a shared signature partial for the champion_signup_mailer views so future emails stay consistent

2. Zip → District/Region Translation

Schema: add_reference :champion_signups, :district, foreign_key: true, null: true

Model (ChampionSignup):

• belongs_to :district, optional: true
• before_save :assign_district_from_zip, if: :will_save_change_to_zip_code? — mirrors Cp::Champion#assign_district_from_zip using ZipCode.lookup
• region delegated through district

Backfill: migration (or rake task per launch-guide conventions) that loops signups with zip_code present and assigns district. Data check (2026-07-09): 158/236 signups have zip; all v1 street-address records also have zip_code populated — no address parsing needed. 78 records have no location data; they stay nil.

Display: wherever the index/show/dashboard shows “location” or “address”, lead with District — Region (e.g. “Nashville — Southeast”). Fallback when district is nil: City, ST if present, else raw zip, else em dash. Full street address (v1) demoted to secondary detail on the show page.

3. District Filter on Signups Index

• Reuse the district-autocomplete Stimulus controller + /api/districts endpoint exactly as /alumni_search does (app/views/alumni/search.html.erb lines ~105–130)
• Controller: permit :district, filter where(district_id: District.find_by(code: params[:district])&.id) (match alumni_search param semantics — district code param)
• Filter chip/clear behavior consistent with existing filters on the page

4. Honeypot Spam Guard

Applies to Public::ChampionSignups#create (step 1) and #request_link (profile-link form).

• Hidden text field with an attractive name (e.g. website), visually hidden via CSS (not display:none inline — position off-screen), tabindex="-1", autocomplete="off"
• Minimum-time trap: signed timestamp in a hidden field (or session) when the form renders; submissions faster than ~3s are treated as bots
• On trip: log (Rails.logger.info with tag for later analysis), do not create the record or send email, render the same success response the real flow would (silent fake success)
• Tests: honeypot filled → no record/email + success response; fast submit → same; legit submit unaffected

5. Champion Signups Dashboard + Nav Restructure

Layout & Routes

• New layout layouts/signups.html.erb + champion_signups/_sidebar.html.erb, modeled on layouts/champions.html.erb / champions/_sidebar.html.erb
• /champion_signups root becomes the Dashboard action; current index moves to /champion_signups/all (mirrors champions/champions#index + all) — keep controller top-level (not champions/) per namespace rules

Sidebar (initial)

Section	Items
Overview	Dashboard
Signups	All Signups (count badge), Duplicates (badge when > 0)
Analytics	Insights
Links	Alumni Network Admin (→ /champions), Back to Alumni Lookup

Dashboard widgets (modeled on Alumni Network dashboard)

• Quick stats: total signups, completed, in progress, last 30 days
• Recent signups list (name, district, status, timestamp)
• Top districts (count per district, top 5)
• Completion funnel by status (step reached)
• CSV export shortcut

Navbar dropdown

• “Champion Program” section → “Champion Signups”: Dashboard, Insights
• Remove “Dashboard” (Network), “Verification Queue”, and “(Legacy)” label from dropdown (both desktop and mobile menus in layouts/_navbar.html.erb)

Explicitly Deferred

• Signature unification for cp/champion_mailer (Alumni Portal Devise emails) — out of scope by decision
• Region-level filter on signups index (district only, matching alumni_search)
• Honeypot on other public forms beyond the signup flow

Acceptance Tests

• All three signup mailer emails (html + text) sign “The Belmont Alumni Engagement Team”
• New signup with valid zip persists district_id; invalid/unknown zip leaves it nil
• Backfill assigns districts to zip-bearing records (157/158 in dev — see deviation note)
• Index filters by district via autocomplete; clears correctly
• Honeypot-tripped submission: success response, zero records, zero emails
• /champion_signups renders dashboard; /champion_signups/all renders the list; old bookmarks to index don’t 404
• Dropdown shows Champion Signups section only; Network reachable via sidebar link
• bin/test — 0 failures (4599 runs)

What Was Implemented (2026-07-09)

1. Signature — shared/email/_team_signature (html + text) rendered by all three signup mailer emails. Admin notification also gained a Location row (District — Region).
2. District translation — district_id on champion_signups (migration backfills in-place), belongs_to :district, before_save :assign_district_from_zip (strips non-digits; self-heals nil districts on save; never overwrites v1 city/state), #region, #location_label. District has_many :champion_signups, dependent: :nullify.
3. District filter — district-autocomplete + /api/districts on /champion_signups/all; controller matches Alumni.filter_by_district semantics (code or id; unknown → none). Location column/show/detail views lead with District — Region, falling back to city/state, then zip.
4. Honeypot — SignupHoneypot service (off-screen website field + signed form_ts min-time trap) on step 1 and profile-link forms. Trips respond with silent fake success (no record/email) and log [honeypot] with IP/UA.
5. Dashboard — layouts/signup_admin + champion_signups/_sidebar (reuses champion-admin-sidebar Stimulus controller). index = dashboard (quick stats, recent signups, top districts, completion funnel, duplicates alert); list moved to all (stat cards removed; destroy/merge redirects updated). Navbar dropdown section renamed “Champion Signups” (Dashboard + Signup Insights); Alumni Network links removed from dropdown, reachable via sidebar “Alumni Network Admin”.
6. Mobile optimization (added mid-phase by user request) — /champion_signups/all follows the /champions/champions/all pattern: sm:hidden tappable card list (name, v2/status/BUID/duplicate badges, location, date, mobile pagination) + hidden sm:block desktop table. Filters trimmed to Status/Role/District visible; Interest/Submitted/Affinity filters collapsed into a “More filters” disclosure (auto-open when active).

Deployment Notes

• One migration: 20260709120000_add_district_to_champion_signups — adds the column and backfills district_id from zip in-place (low risk, ~240 rows, ran in <1s in dev). No rake task needed; rows created between deploy and migrate self-heal on next save.
• No new ENV vars, hosts, or placeholder URLs.
• Post-deploy check: ChampionSignup.where.not(zip_code: [nil,'']).where(district_id: nil).count should be ≈0 (the known quote-wrapped spam zip heals on next save or can be deleted).
• QA focus: honeypot (submit signup normally on a phone — must succeed), dashboard + /all on mobile widths, district filter, old /champion_signups bookmarks land on the dashboard.

Spec Deviations

• Dead duplicates route/action removed instead of linked: it never had a template (would 500); duplicates review is /champion_signups/all?status=duplicates, which the sidebar and dashboard link to.
• Honeypot fake success on step 1 redirects to the signup landing rather than a fabricated profile-hub URL (no record exists to tokenize); profile-link trips redirect identically to the real flow (link_sent=true).
• Backfill matched 157/158 — the unmatched row is the known spam signup (id 334) whose zip was stored with literal quote characters; the model’s digit-stripping now handles that pattern going forward.
• Admin notification also signed — spec listed it as “normalize”; user asked for all emails, so it got the full signature.