113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
# Policies & Safety Protocols Integration
|
|
|
|
## Purpose
|
|
|
|
Two document 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`, reported in
|
|
leadership dashboards, and listed for each user in Profile.
|
|
|
|
## 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`
|
|
|
|
Acknowledgment tracking:
|
|
|
|
- Dashboard component:
|
|
`frontend/src/components/director-dashboard/DirectorAcknowledgmentTrackingPanel.tsx`
|
|
- Business/API: `buildDirectorAcknowledgmentDocuments` +
|
|
`usePolicyAcknowledgmentReport` in
|
|
`frontend/src/business/director-dashboard` and
|
|
`frontend/src/business/policies/hooks.ts`, backed by
|
|
`frontend/src/shared/api/policyAcknowledgments.ts`
|
|
- Profile: `buildProfileDocumentAcknowledgmentRows` feeds the profile's
|
|
current document checklist. The checklist includes every visible active
|
|
current-version Safety Protocol and Handbook & Policies document, shows a
|
|
status badge beside the title, and uses the `Acknowledged on` column only for
|
|
the acknowledgment date.
|
|
|
|
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)
|
|
- `GET /api/policy_acknowledgments/report` (manager report for current tenant
|
|
scope: summary totals, per-document completion, and per-staff statuses)
|
|
|
|
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.
|
|
- **Acknowledgment report** is available to owner, superintendent, principal,
|
|
registrar, and director. Super/system admins can read it only while drilled
|
|
into a tenant. The report counts active director/office_manager/teacher/
|
|
support_staff accounts in the current scope. The leadership dashboard renders
|
|
acknowledgment tracking as a collapsible section in the main dashboard flow
|
|
and scrolls to it from the Acknowledgments overview metric or the aggregated
|
|
acknowledgment risk card. When expanded, the section groups current-version
|
|
documents by category, shows collapsed acknowledged/total counts, expands to
|
|
missing staff names, and the risk area aggregates missing acknowledgments into
|
|
one concise card.
|
|
- **User notifications** remain driven by current-version missing acknowledgments
|
|
for visible active Safety Protocol and Handbook & Policies documents.
|
|
- **Profile document checklist** lists active current-version documents visible
|
|
to the user, sorts missing acknowledgments first, marks each row as
|
|
acknowledged or not acknowledged with a title badge, and shows the
|
|
acknowledgment date separately when present.
|
|
- Management is gated by effective policy-document permissions, mirroring the backend grant.
|
|
- Both pages are seeded from `20260611050000-policy-documents-seed.ts`; fixture
|
|
seed data presets the same document set at organization, school, and campus
|
|
scopes for both demo tenants.
|
|
|
|
## Tests
|
|
|
|
- `business/policies/mappers.test.ts`, `business/policies/selectors.test.ts`
|
|
- `business/safety-protocols/mappers.test.ts`,
|
|
`business/safety-protocols/selectors.test.ts`
|
|
- `business/director-dashboard/selectors.test.ts`
|
|
- `business/profile/selectors.test.ts`
|
|
|
|
## Verification
|
|
|
|
- `npm run typecheck`, `npm run lint`, `npm run test` pass.
|