admin/40227-vm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
40227-vm/frontend/docs/policies-integration.md

5.5 KiB
Raw Blame History

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/DirectorAcknowledgmentTrackingModal.tsx and 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 opens acknowledgment tracking in a modal from the Acknowledgments overview metric or the aggregated acknowledgment risk card. The modal 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.