docs(phase5c): enrollment communications documentation + Google Workspace runbook

- PHASE5C_ENROLLMENT_COMMUNICATIONS.md: the full design doc.
- RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md: every REQUIRES GOOGLE WORKSPACE ADMIN ACTION step
  (mailbox, service account, domain-wide delegation scoped to gmail.send only, SPF/DKIM/DMARC),
  environment variables, testing procedure, production secret handling, rotation, revocation,
  troubleshooting, quotas.
- RUNBOOK_STUDENT_ACTIVATION.md: day-to-day operation of the pipeline from /admin.
- WEBSITE_ENROLLMENT_INTEGRATION.md: explicit website-vs-RootNode responsibility boundary,
  the new contact_email field, and closes the 'RootNode doesn't send activation email yet'
  known limitation this doc previously documented.
- RUNBOOK_SELF_PACED_ENROLLMENT.md, RUNBOOK_STUDENT_ACCOUNT_LIFECYCLE.md: point at the new
  automatic-email behavior and the Resend activation control.
- REMOTE_AND_SELF_PACED_ARCHITECTURE.md, ENGINEERING_SOP.md: close the enrollment-
  communication gap; new ENGINEERING_SOP §16.
- PRODUCTION_VALIDATION_CHECKLIST.md, README.md, platform/README.md: cross-references and a
  Phase 5C production-validation section.
This commit is contained in:
2026-08-25 14:45:18 -05:00
parent b38c46aaec
commit 777efd168d
11 changed files with 595 additions and 29 deletions
+31
View File
@@ -388,3 +388,34 @@ Full design: `docs/PHASE5B_SELF_PACED_ENROLLMENT.md`, plus
real capstone completion, integration-endpoint concurrency, and a real Platform API restart.
Migration safety proven explicitly against a fresh Postgres seeded with realistic pre-5B data
(see that doc §14).
## 16. Enrollment Operations & Communications (Phase 5C)
Full design: `docs/PHASE5C_ENROLLMENT_COMMUNICATIONS.md`, plus
`docs/RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md` and `docs/RUNBOOK_STUDENT_ACTIVATION.md`.
- **What it is:** a durable, provider-neutral notification pipeline (`notification_events`, a
`FOR UPDATE SKIP LOCKED` worker polling on a plain `setInterval` — same pattern as the
existing session/login-attempt sweepers, no new infrastructure) that finally sends real email
for activation, enrollment confirmation, password reset, and password-changed — closing the
gap Phase 5A explicitly left open. Google Workspace adapter: Gmail API via a service account
with domain-wide delegation (no human password, no SMTP basic auth — see that doc §2 for why),
behind the same provider interface a deterministic dev provider implements, so no test or dev
run ever reaches a real inbox. Reuses Phase 5A's activation/reset token mechanism entirely — no
competing invitation-token system.
- **A real bug found and fixed:** `request-password-reset` would mint a reset token for a
never-activated student, which doesn't make sense (there's no password yet to reset) and would
have sent a confusing email. Fixed to fall through to the same anti-enumeration response as a
nonexistent account.
- **Tested, not just designed:** `platform/test/e2e-phase5c.js` (28 checks: activation vs.
confirmation routing, duplicate/concurrent webhook idempotency, temporary/permanent/exhausted
retry classification, resend/regenerate token invalidation, production token-secrecy gating
via a real container recreate with `COOKIE_SECURE=1`, minor/contact-email resolution, RBAC
scoping, metrics/audit hygiene, a real restart) and
`infra/scripts/drills/test-phase5c-enrollment-activation.js` (10 checks: one continuous story
from website enrollment through a real rendered/extracted activation email, a real Lab launch
and scenario completion, a second enrollment's confirmation email, and a full password-reset
round trip) — both against a live stack, using only the dev provider (no real network calls).
Live Google Workspace delivery itself is implemented and unit-level ready
(`infra/scripts/gws-email-test.js`, opt-in) but not yet validated against a real Workspace
domain — see that doc's final section.