# 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

- [x] Unit tests passed (7/7 tests passed in `vitest tests/offboardingService.test.js`).
- [x] Knex migration applied cleanly during database initialization.