geocrop-platform./apps/nextgen/.harness/changelogs/2026-07-22-offboarding.md

2026-07-22 — Phase 3: Offboarding Workflows (Students + Staff)

Branch: feature/offboarding-2026-07-22 Owner: Craig Scope: single, transaction-backed, auditable wizard process for both students and staff offboarding.

What landed

Turned offboarding from a multi-step manual process into a single transaction-backed wizard producing a clean, audited record.

Schema

• New Knex migration 2026072300000010_offboarding.js:
  • offboarding_records — case tracking for student and staff offboardings (audience, reason, status, effective date, destination, alumni status, audit metadata).
  • offboarding_actions — per-step audit trail matching the 11 pipeline stages.
  • users.archive_status — altered users table to add column check constraint (active_alumni, inactive_alumni, former_staff).
  • Standard sync columns (uid, sync_status, last_synced_at, is_deleted) added to new tables.

Backend

• server/src/services/OffboardingService.js (new) — Pipeline logic running student and staff offboardings in a single SQLite transaction (db.transaction()). Step failures rollback all modifications.
• server/src/controllers/offboarding.controller.js (new) — Endpoints for:
  • POST /students/:userId & POST /staff/:userId
  • GET /preflight/:userId — pre-check for active assignments, fees, or payroll blocks.
  • GET /records & GET /records/:id
  • POST /records/:id/cancel — cancel offboarding and re-activate user login.
  • POST /records/:id/override — administrator override of fee or payroll blocks.
  • GET /alumni — alumni directory with cohort/year filters.
  • GET /former-staff — former staff list with department filters.
• server/src/index.js — controller mounted at /api/offboarding
• server/src/services/SyncEngine.js — offboarding tables appended to tablesToSync in dependency order.

Frontend

• client/src/store/offboarding.ts (new) — Zustand store slice for state management, actions, preflights, and listings.
• client/src/pages/admin/Offboarding.tsx (new) — Offboarding dashboard directory separating students and staff listings, with details drawer and workflow cancellation triggers.
• client/src/pages/admin/OffboardingWizard.tsx (new) — Multi-step wizard executing preflight validation, checklist rendering, override modal capture, and final transaction execution.
• client/src/pages/admin/Alumni.tsx (new) — Directory search for former students with cohort, year, and reason filters.
• client/src/components/OffboardingStepRow.tsx (new) — Status row indicator for wizard step checklists.
• client/src/components/OverrideModal.tsx (new) — Modal capturing administrative override justification.
• client/src/App.tsx — Mounted Offboarding routes (gated by roles).
• client/src/components/Nav.tsx — Sidebar entries for Offboarding and Alumni Directory.
• client/src/pages/admin/Users.tsx — "Offboard" button in student row actions.
• client/src/pages/admin/HRManagement.tsx — "Offboard" button in staff details modal footer.
• client/src/pages/hr/StaffDirectory.tsx — "Offboard" button in staff details drawer.

E2E & Unit Tests

• server/tests/offboardingService.test.js (new) — Vitest suite validating:
  • Student offboarding happy path.
  • Student fee block (and override path).
  • Staff offboarding happy path.
  • Staff payroll block (and override path).
  • Subject/class unassignments and role revocation.
  • Transaction rollback on intermediate step constraint failures.
• client/e2e/offboarding.spec.ts (new) — Playwright E2E test verifying:
  • Student offboarding checklist.
  • Outstanding fee blocks and admin bypass overrides.
  • Staff offboarding flow.
  • Offboarding cancellation (user re-activation).

Decisions / why

• Transaction atomicity is absolute. Bypassing individual queries is avoided by bundling all database updates (close enrollment, release room, clear transport, unassign teacher, revoke auxiliary roles, de-activate login, insert audit record, and insert step actions) in a single SQLite transaction wrapper.
• Audit trail is integrated into transaction connection. Added custom database handle support (details.db) to AuditService.log to write audits using the same active transaction, ensuring audit logs roll back on failures.
• Reopen cancels, keeping history. Restoring user account de-activates deactivation, but keeps all previous step action records in the offboarding tables to maintain a historical log of what happened.

Verification

• Unit tests passed (7/7 tests passed in vitest tests/offboardingService.test.js).
• Knex migration applied cleanly during database initialization.