Policies & Safety Protocols Integration

Purpose

Two pages — Handbook & Policies and Safety Protocols — are backed by one unified store, policy_documents (it replaced the former generic documents API, which has been removed). category selects the page (handbook_policy vs safety_protocol); tag carries the finer sub-category (the handbook's Operations/Behavior/… and the safety card icon). Staff acknowledgment is persisted per document version via policy_acknowledgments.

Frontend Structure

Handbook & Policies:

Framework wrapper: frontend/src/components/frameworks/HandbookPolicy.tsx
View components: frontend/src/components/policies/
Business: frontend/src/business/policies/{hooks,pageHooks,mappers,selectors}.ts

Safety Protocols:

Module: frontend/src/components/safety-protocols/SafetyProtocolsModule.tsx (+ SafetyProtocolForm.tsx, SafetyDynamicListEditor.tsx)
Business: frontend/src/business/safety-protocols/{hooks,mappers,selectors,types}.ts

Shared:

API layer: frontend/src/shared/api/policyDocuments.ts, frontend/src/shared/api/policyAcknowledgments.ts
DTO types: frontend/src/shared/types/policyDocuments.ts
Types/constants: frontend/src/shared/types/policies.ts, frontend/src/shared/constants/policies.ts, frontend/src/shared/constants/safetyProtocols.ts

Backend Contract

GET /api/policy_documents?category=<handbook_policy|safety_protocol>
POST /api/policy_documents, PUT /api/policy_documents/:id, DELETE /api/policy_documents/:id
GET /api/policy_acknowledgments (caller's own), POST /api/policy_acknowledgments ({ data: { policyDocumentId } } → acknowledges the current version)

A policy_documents row carries: title, body, category, tag, author (display name of the creating user, server-set), steps + autism_considerations (JSONB string arrays — author-filled structured content for safety protocols), version (bumped on title/body/steps/considerations change), active, tenant organizationId + nullable campusId.

Behavior

Handbook: HandbookPolicy calls usePoliciesPage and renders PoliciesView (hero, create/edit form, filters, list, cards, empty state). Sub-category maps to/from tag. Full add/edit/delete.
Safety Protocols: SafetyProtocolsModule lists safety_protocol docs, rendering author-filled steps + autism considerations with a static per-tag icon. Managers get a FRAME-style authoring flow (header New Protocol → SafetyProtocolForm, per-card Edit/Delete) with dynamic steps + considerations rows (SafetyDynamicListEditor, add/remove per protocol).
Acknowledgment is persisted (usePolicyAcknowledgments / useAcknowledgePolicy, shared by both pages) — it replaced the former session-local set. Re-acknowledgment is required after a version bump and is idempotent within a version.
Management is gated by canManagePolicies / canManageSafetyProtocols (owner/superintendent/director/office_manager), mirroring the backend grant.
Both pages are seeded from 20260611050000-policy-documents-seed.ts.

Tests

business/policies/mappers.test.ts, business/policies/selectors.test.ts
business/safety-protocols/mappers.test.ts, business/safety-protocols/selectors.test.ts

Verification

npm run typecheck, npm run lint, npm run test pass.

3.3 KiB Raw Blame History