72 lines
4.6 KiB
Markdown
72 lines
4.6 KiB
Markdown
# 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.
|