# 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.