Policy Documents & Acknowledgments

Workstream 11 — persistence of staff acknowledgment of policy/safety documents.

Purpose

Campus staff must acknowledge two categories of documents — Safety Protocols (official/government) and Handbook & Policies (internal). director and office_manager author the documents; all four campus staff roles (director, office_manager, teacher, support_staff) acknowledge them. Acknowledgment is per document version: editing a document bumps its version, which requires re-acknowledgment.

Frontend wiring

The two existing pages consume this single store (the old generated documents entity it replaced has been removed):

Handbook & Policies (business/policies) lists policy_documents of category = handbook_policy, mapping the handbook's sub-category to/from tag (toPolicyViewModel / toPolicyDocumentMutationDto). Management is gated to owner/superintendent/director/office_manager (canManagePolicies, mirroring the backend grant). Acknowledgment is persisted via policy_acknowledgments (usePolicyAcknowledgments / useAcknowledgePolicy), replacing the former local-state set.
Safety Protocols (business/safety-protocols) consumes category = safety_protocol, rendering author-filled steps + autism considerations with a static per-tag card icon (fire/shield/heart). It shares the persistent acknowledgment hooks. Both pages are seeded from 20260611050000-policy-documents-seed.ts (safety protocols reuse the former content-catalog safetyProtocols payload; a few handbook policies seed the handbook page). The Safety Protocols page also has a manager-gated structured-authoring flow (mirrors the F.R.A.M.E. module: header New Protocol button → create form, per-card Edit/Delete) with dynamic steps + autismConsiderations rows that add/remove independently, so each protocol carries its own count (useSafetyProtocolsModule + SafetyProtocolForm / SafetyDynamicListEditor; gated by canManageSafetyProtocols, which reuses the policy grant). Title/body/steps/considerations changes bump version and require re-acknowledgment.

Entities

policy_documents (generic-CRUD entity): title, body, category (safety_protocol | handbook_policy — selects the page), tag (nullable finer sub-category; the Handbook page maps its Operations/Behavior/Safety/Communication/Legal categorisation onto it, and the Safety page uses it to pick the static card icon), author (display name of the creating user, set server-side at creation and not changed on update), steps + autism_considerations (JSONB string arrays — author-filled structured content for safety protocols; null for handbook policies), version (bumped when title/body/steps/autism_considerations change), active, tenant organizationId + nullable campusId. This is the single unified store for both the Safety Protocols and Handbook & Policies pages (filter by ?category= and optionally ?tag=). The category list + icons are static frontend config; each document's category assignment (tag) is DB data. author is derived from the current user's name — ${name_prefix} firstName lastName (the honorific title from users.name_prefix, e.g. "Dr. Sarah Williams"), else email.
policy_acknowledgments (per-user): one row per (userId, policyDocumentId, version), with acknowledgedAt. Unique index on those three columns; acknowledging is idempotent for a given version.

Routes

GET/POST /api/policy_documents, PUT/DELETE /api/policy_documents/:id, plus the standard generic-CRUD extras — guarded by checkCrudPermissions('policy_documents') (${METHOD}_POLICY_DOCUMENTS).
GET /api/policy_acknowledgments (the caller's own acknowledgments) and POST /api/policy_acknowledgments ({ data: { policyDocumentId } } → acknowledges the document's current version) — both guarded by checkPermissions('ACK_POLICY').

Authorization

READ_POLICY_DOCUMENTS — granted to the four campus roles (director via full access; office_manager/teacher/support via the read-only entity grant). student/guardian get no policy-document access.
CREATE/UPDATE/DELETE_POLICY_DOCUMENTS — director (full access) and office_manager (explicit grant in the role seeder). teacher/support_staff are read-only.
ACK_POLICY — the four campus roles (a product-feature action permission; extendable per user via custom_permissions).

Tenant/campus scoping is applied in the data layer (tenantWhere / findOwnedByPk); acknowledgment reads are additionally restricted to the caller's own userId. A manager-facing acknowledgment-status report (audience TBD) is a deferred refinement.

Tests

Unit (backend/src/shared/constants/policy-documents.test.ts + users.test.ts, npm test): the pure domain rules — isPolicyDocumentCategory validation, the nextPolicyDocumentVersion re-acknowledgment bump, and formatPersonName (author rendering).
Frontend unit (vitest): business/policies/mappers.test.ts (handbook; tag↔category, author), business/safety-protocols/mappers.test.ts (steps + autism considerations) and business/safety-protocols/selectors.test.ts (management grant + draft validation for the authoring form).
Seeded e2e (frontend/tests/e2e/policy-acknowledgments.seeded.e2e.ts, npm run test:e2e:content): document create/persist, manage-vs-read RBAC (director/office_manager manage; teacher reads but cannot create), idempotent per-version acknowledgment, version-bump re-acknowledgment, and external-role lockout.

Open / deferred

Acknowledgment-status reporting for managers (who-acknowledged-what) — pending the report-audience decision.
The acknowledgment + document-management UI is design-gated (see docs/backlog.md).

5.9 KiB Raw Blame History